Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@material/textfield

Package Overview
Dependencies
Maintainers
15
Versions
1703
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@material/textfield

The Material Components for the web text field component

  • 14.0.0
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
743K
decreased by-6.73%
Maintainers
15
Weekly downloads
 
Created
Source

Text field

Text fields let users enter and edit text.

For more information, see the API documentation.

The text field class consists of the following types:

Text field examples of both filled and outlined types, and each type showing both inactive and focused states.

Using text fields

Text fields allow users to enter text into a UI. They typically appear in forms and dialogs.

Installation

npm install @material/textfield

Styles

@use "@material/floating-label/mdc-floating-label";
@use "@material/line-ripple/mdc-line-ripple";
@use "@material/notched-outline/mdc-notched-outline";
@use "@material/textfield";

@include textfield.core-styles;

JavaScript instantiation

import {MDCTextField} from '@material/textfield';

const textField = new MDCTextField(document.querySelector('.mdc-text-field'));

Note: See Importing the JS component for more information on how to import JavaScript.

Filled text

Filled text fields have more visual emphasis than outlined text fields, making them stand out when surrounded by other content and components.

Filled text example

<label class="mdc-text-field mdc-text-field--filled">
  <span class="mdc-text-field__ripple"></span>
  <span class="mdc-floating-label" id="my-label-id">Hint text</span>
  <input class="mdc-text-field__input" type="text" aria-labelledby="my-label-id">
  <span class="mdc-line-ripple"></span>
</label>

Outlined text

Outlined text fields have less visual emphasis than filled text fields. When they appear in places like forms, where many text fields are placed together, their reduced emphasis helps simplify the layout.

Outlined text example

<label class="mdc-text-field mdc-text-field--outlined">
  <span class="mdc-notched-outline">
    <span class="mdc-notched-outline__leading"></span>
    <span class="mdc-notched-outline__notch">
      <span class="mdc-floating-label" id="my-label-id">Your Name</span>
    </span>
    <span class="mdc-notched-outline__trailing"></span>
  </span>
  <input type="text" class="mdc-text-field__input" aria-labelledby="my-label-id">
</label>

See here for more information on using the notched outline sub-component.

Note: Do not use mdc-line-ripple inside of mdc-text-field if you plan on using mdc-text-field--outlined. Line Ripple should not be included as part of the DOM structure of an outlined text field.

Other variations

Textarea

Filled
<label class="mdc-text-field mdc-text-field--filled mdc-text-field--textarea mdc-text-field--no-label">
  <span class="mdc-text-field__ripple"></span>
  <span class="mdc-text-field__resizer">
    <textarea class="mdc-text-field__input" rows="8" cols="40" aria-label="Label"></textarea>
  </span>
  <span class="mdc-line-ripple"></span>
</label>
Outlined
<label class="mdc-text-field mdc-text-field--outlined mdc-text-field--textarea mdc-text-field--no-label">
  <span class="mdc-notched-outline">
    <span class="mdc-notched-outline__leading"></span>
    <span class="mdc-notched-outline__trailing"></span>
  </span>
  <span class="mdc-text-field__resizer">
    <textarea class="mdc-text-field__input" rows="8" cols="40" aria-label="Label"></textarea>
  </span>
</label>

Note: The mdc-text-field__resizer element may be omitted for a non-resizable textarea.

Text field without label

A text field doesn’t require a label if a separate but clear label indicator is already displayed adjacent to the text field. Add class name mdc-text-field--no-label and remove the label element from the structure.

Filled
<label class="mdc-text-field mdc-text-field--filled mdc-text-field--no-label">
  <span class="mdc-text-field__ripple"></span>
  <input class="mdc-text-field__input" type="text" placeholder="Placeholder text" aria-label="Label">
  <span class="mdc-line-ripple"></span>
</label>
Outlined
<label class="mdc-text-field mdc-text-field--outlined mdc-text-field--no-label">
  <span class="mdc-notched-outline">
    <span class="mdc-notched-outline__leading"></span>
    <span class="mdc-notched-outline__trailing"></span>
  </span>
  <input class="mdc-text-field__input" type="text" aria-label="Label">
</label>
Textarea
<label class="mdc-text-field mdc-text-field--outlined mdc-text-field--textarea mdc-text-field--no-label">
  <span class="mdc-notched-outline">
    <span class="mdc-notched-outline__leading"></span>
    <span class="mdc-notched-outline__trailing"></span>
  </span>
  <span class="mdc-text-field__resizer">
    <textarea class="mdc-text-field__input" rows="8" cols="40" aria-label="Label"></textarea>
  </span>
</label>

Disabled text field

To disable the text field, add the disabled attribute to the <input> element and add the mdc-text-field--disabled class to the mdc-text-field element.

<label class="mdc-text-field mdc-text-field--filled mdc-text-field--disabled">
  <span class="mdc-text-field__ripple"></span>
  <span class="mdc-floating-label" id="my-label-id">Disabled text field</span>
  <input class="mdc-text-field__input" type="text" aria-labelledby="my-label-id" disabled>
  <span class="mdc-line-ripple"></span>
</label>

Text field with helper text

The helper text provides supplemental information and/or validation messages to users. It appears on input field focus and disappears on input field blur by default, or it can be persistent. Helper text should be rendered inside .mdc-text-field-helper-line element which is immediate sibling of .mdc-text-field. See here for more information on using helper text.

<label class="mdc-text-field mdc-text-field--filled">
  <span class="mdc-text-field__ripple"></span>
  <span class="mdc-floating-label" id="my-label-id">My Label</span>
  <input class="mdc-text-field__input" type="text"
         aria-labelledby="my-label-id"
         aria-controls="my-helper-id"
         aria-describedby="my-helper-id">
  <span class="mdc-line-ripple"></span>
</label>
<div class="mdc-text-field-helper-line">
  <div class="mdc-text-field-helper-text" id="my-helper-id" aria-hidden="true">helper text</div>
</div>

Text field with character counter

Character counter is used if there is a character limit. It displays the ratio of characters used and the total character limit. Character counter should be rendered inside .mdc-text-field-helper-line element which is immediate sibling of .mdc-text-field. See here for more information on using character counter.

<label class="mdc-text-field mdc-text-field--filled">
  <span class="mdc-text-field__ripple"></span>
  <span class="mdc-floating-label" id="my-label-id">My Label</span>
  <input class="mdc-text-field__input" type="text" aria-labelledby="my-label-id" maxlength="10">
  <span class="mdc-line-ripple"></span>
</label>
<div class="mdc-text-field-helper-line">
  <div class="mdc-text-field-character-counter">0 / 10</div>
</div>

Multi-line text field (textarea) with character counter

A character counter can be associated with a textarea by including it in the helper line. In this case, the counter will appear below the textarea, adjacent to any helper text.

<label class="mdc-text-field mdc-text-field--textarea">
  <span class="mdc-notched-outline">
    <span class="mdc-notched-outline__leading"></span>
    <span class="mdc-notched-outline__notch">
      <span class="mdc-floating-label" id="my-label-id">Textarea Label</span>
    </span>
    <span class="mdc-notched-outline__trailing"></span>
  </span>
  <span class="mdc-text-field__resizer">
    <textarea class="mdc-text-field__input" aria-labelledby="my-label-id" rows="8"
      cols="40" maxlength="140"></textarea>
  </span>
</label>
<div class="mdc-text-field-helper-line">
  <div class="mdc-text-field-character-counter">0 / 140</div>
</div>

Alternatively, the character counter can be placed in the textarea's body by inserting the character counter below the textarea and adding the mdc-text-field--with-internal-counter modifier class to the text field.

<label class="mdc-text-field mdc-text-field--outlined mdc-text-field--textarea mdc-text-field--with-internal-counter">
  <span class="mdc-notched-outline">
    <span class="mdc-notched-outline__leading"></span>
    <span class="mdc-notched-outline__notch">
      <span class="mdc-floating-label" id="my-label-id">Textarea Label</span>
    </span>
    <span class="mdc-notched-outline__trailing"></span>
  </span>
  <span class="mdc-text-field__resizer">
    <textarea class="mdc-text-field__input" aria-labelledby="my-label-id" rows="8" cols="40" maxlength="140"></textarea>
    <span class="mdc-text-field-character-counter">0 / 140</span>
  </span>
</label>

Helper text and Character counter are optional subcomponents of text field that can co-exist independently. It is recommended that .mdc-text-field and .mdc-text-field-helper-line elements have same width for correct layout.

Text field with prefix and suffix text

Prefix and suffix text can add context to a text field, such as a currency symbol prefix or a unit of mass suffix. A prefix, suffix, or both can be added within the default or outlined variants of text fields.

<label class="mdc-text-field mdc-text-field--filled">
  <span class="mdc-text-field__ripple"></span>
  <span class="mdc-floating-label" id="my-label-id">Currency Value</span>
  <span class="mdc-text-field__affix mdc-text-field__affix--prefix">$</span>
  <input class="mdc-text-field__input" type="text" aria-labelledby="my-label-id">
  <span class="mdc-text-field__affix mdc-text-field__affix--suffix">.00</span>
  <span class="mdc-line-ripple"></span>
</label>

Note: Do not use mdc-text-field--affix within mdc-text-field--textarea.

Text field with leading and trailing icons

Leading and trailing icons can be added within the default or outlined variant of MDC Text Field as visual indicators as well as interaction targets. See here for more information on using icons.

Other features

HTML5 validation

MDCTextFieldFoundation provides validity styling by using the :invalid and :required attributes provided by HTML5's form validation API.

<label class="mdc-text-field mdc-text-field--filled">
  <span class="mdc-text-field__ripple"></span>
  <span class="mdc-floating-label" id="my-label-id">Password</span>
  <input class="mdc-text-field__input" type="password" aria-labelledby="my-label-id" required minlength="8">
  <span class="mdc-line-ripple"></span>
</label>

MDCTextFieldFoundation automatically appends an asterisk to the label text if the required attribute is set.

Pre-filled

When dealing with JS-driven text fields that already have values, you'll want to ensure that you render mdc-text-field with the mdc-text-field--label-floating modifier class, as well as mdc-floating-label with the mdc-floating-label--float-above modifier class. This will ensure that the label moves out of the way of the text field's value and prevents a Flash Of Un-styled Content (FOUC).

<label class="mdc-text-field mdc-text-field--filled mdc-text-field--label-floating">
  <span class="mdc-text-field__ripple"></span>
  <span class="mdc-floating-label mdc-floating-label--float-above" id="my-label-id">
    Label in correct place
  </span>
  <input class="mdc-text-field__input" type="text" aria-labelledby="my-label-id" value="Pre-filled value">
  <span class="mdc-line-ripple"></span>
</label>

Baseline alignment

By default, text fields will be aligned with other elements relative to their baseline. The input text's baseline is used to determine where a text field should be aligned to and is different between variants. To force alignment to the text field's container instead of its baseline, align the element using flexbox.

<div>
  <label class="mdc-text-field mdc-text-field--outlined">
    <span class="mdc-notched-outline">
      <span class="mdc-notched-outline__leading"></span>
      <span class="mdc-notched-outline__trailing"></span>
    </span>
    <input type="text" class="mdc-text-field__input" value="Baseline">
  </label>
  <span>Text that is aligned with the text field's value</span>
</div>

<div style="display: flex; flex-direction: row; align-items: flex-end;">
  <label class="mdc-text-field mdc-text-field--outlined">
    <span class="mdc-notched-outline">
      <span class="mdc-notched-outline__leading"></span>
      <span class="mdc-notched-outline__trailing"></span>
    </span>
    <input type="text" class="mdc-text-field__input" value="Baseline">
  </label>
  <span>Text that is aligned to the bottom of the text field's outline</span>
</div>

API

CSS classes

CSS ClassDescription
mdc-text-fieldMandatory.
mdc-text-field--filledStyles the text field as a filled text field.
mdc-text-field--outlinedStyles the text field as an outlined text field.
mdc-text-field--textareaIndicates the text field is a <textarea>.
mdc-text-field--disabledStyles the text field as a disabled text field.
mdc-text-field--with-leading-iconStyles the text field as a text field with a leading icon.
mdc-text-field--with-trailing-iconStyles the text field as a text field with a trailing icon.
mdc-text-field--focusedStyles the text field as a text field in focus.
mdc-text-field--no-labelStyles the text field that has no label.
mdc-text-field--end-alignedStyles the text field with an end-aligned input.
mdc-text-field--label-floatingStyles the text field with a floating label and pre-filled or focused value.
mdc-text-field--ltr-textStyles the text field's text elements (input, prefix, and suffix) as LTR even when the direction is RTL. Useful for RTL languages that use LTR for fractional notations.
mdc-text-field--with-internal-counterStyles the text area as a text area with an internal character counter.
mdc-text-field-helper-lineStyles the container of helper text and character counter elements.

Sass mixins

To customize the colors of any part of the text-field, use the following mixins. We recommend you apply these mixins within CSS selectors like .foo-text-field:not(.mdc-text-field--focused) to select your unfocused text fields, and .foo-text-field.mdc-text-field--focused to select your focused text-fields. To change the invalid state of your text fields, apply these mixins with CSS selectors such as .foo-text-field.mdc-text-field--invalid.

NOTE: the mdc-line-ripple-color mixin should be applied from the not focused class foo-text-field:not(.mdc-text-field--focused)).

Mixins for all text fields
MixinDescription
ink-color($color)Customizes the color of the text entered into an enabled text field.
placeholder-color($color)Customizes the color of the placeholder in an enabled text field.
disabled-ink-color($color)Customizes the color of the entered text in a disabled text field.
disabled-placeholder-color($color)Customizes the color of the placeholder in a disabled text field.
label-color($color)Customizes the text color of the label in an enabled text field.
disabled-label-color($color)Customizes the text color of the label in a disabled text field.
caret-color($color)Customizes the color of the cursor caret of the text field.
prefix-color($color)Customizes the color of the prefix text of an enabled text field.
disabled-prefix-color($color)Customizes the color of the prefix text of a disabled text field.
suffix-color($color)Customizes the color of the suffix text of an enabled text field.
disabled-suffix-color($color)Customizes the color of the suffix text of a disabled text field.
floating-label-float-transition($duration-ms, $timing-function)Customizes the duration and optional timing function for the floating label's "float" transition.
Mixins for filled text field and textarea
MixinDescription
fill-color($color)Customizes the background color of the text field or textarea when enabled.
disabled-fill-color($color)Customizes the background color of the text field or textarea when disabled.
Mixins for filled text field only
MixinDescription
shape-radius($radius, $rtl-reflexive)Sets rounded shape to boxed text field variant with given radius size. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false.
bottom-line-color($color)Customizes the text field bottom line color.
hover-bottom-line-color($color)Customizes the hover text field bottom line color.
disabled-bottom-line-color($color)Customizes the disabled text field bottom line color.
line-ripple-color($color)Customizes the color of the default line ripple of the text field.
density($density-scale)Sets density scale for default text field variant. Supported density scale values -4, -3, -2, -1, 0.
height($height)Sets height of default text field variant.
Mixins for outlined text field and textarea
MixinDescription
focused-outline-color($color)Customizes the outline border color when the text field or textarea is focused.
hover-outline-color($color)Customizes the outline border color when the text field or textarea is hovered.
disabled-outline-color($color)Customizes the outline border color when the text field or textarea is disabled.
outline-color($color)Customizes the border color of the outlined text field or textarea.
Mixins for outlined text field only
MixinDescription
outline-shape-radius($radius, $rtl-reflexive)Sets rounded shape to outlined text field variant with given radius size. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false.
outlined-density($density-scale)Sets density scale for outlined text field (Excluding outlined text field with leading icon). Supported density scale values -4, -3, -2, -1, 0.
outlined-height($height)Sets height of outlined text field variant (Excluding outlined text field with leading icon).
outlined-with-leading-icon-density($density-scale)Sets density scale for outlined text field with leading icon. Supported density scale values -4, -3, -2, -1, 0.
outlined-with-leading-icon-height($height)Sets height of outlined text field with leading icon variant.
Mixins for textarea only
MixinDescription
textarea-shape-radius($radius, $rtl-reflexive)Sets rounded shape to text area variant with given radius size. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false.
outlined-textarea-density($density-scale)Sets density scale for outlined textarea. Supported density scale values -4, -3, -2, -1, 0.
textarea-min-rows($rows)Sets the minimum number of rows for a textarea a textarea may be resized to.

MDCTextField properties and methods

PropertyValue TypeDescription
valuestringProxies to the foundation's getValue/setValue methods.
disabledbooleanProxies to the foundation's isDisabled/setDisabled methods.
useNativeValidationboolean (write-only)Proxies to the foundation's setUseNativeValidation method.
validbooleanProxies to the foundation's isValid/setValid methods.
helperTextContentstring (write-only)Proxies to the foundation's setHelperTextContent method when set.
rippleMDCRipple (write-only)The MDCRipple instance for the root element that MDCTextField initializes; this only applies to the default Text Field, and is null for other variants.
leadingIconAriaLabelstring (write-only)Proxies to the foundation's setLeadingIconAriaLabel method.
trailingIconAriaLabelstring (write-only)Proxies to the foundation's setTrailingIconAriaLabel method.
leadingIconContentstring (write-only)Proxies to the foundation's setLeadingIconContent method.
trailingIconContentstring (write-only)Proxies to the foundation's setTrailingIconContent method.
prefixTextstringGets or sets the text content of the prefix, if it exists.
suffixTextstringGets or sets the text content of the suffix, if it exists.

In addition to the above, the following properties proxy to the input element's properties of the same name:

  • required
  • pattern
  • minLength
  • maxLength
  • min
  • max
  • step
Method SignatureDescription
focus() => voidFocuses the input or textarea element.
layout() => voidAdjusts the dimensions and positions for all sub-elements.

Usage within frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Text Field for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

MDCTextFieldAdapter

Method SignatureDescription
addClass(className: string) => voidAdds a class to the root element.
removeClass(className: string) => voidRemoves a class from the root element.
hasClass(className: string) => booleanReturns true if the root element contains the given class name.
registerTextFieldInteractionHandler(evtType: string, handler: EventListener) => voidRegisters an event handler on the root element for a given event.
deregisterTextFieldInteractionHandler(evtType: string, handler: EventListener) => voidDeregisters an event handler on the root element for a given event.
registerInputInteractionHandler(evtType: string, handler: EventListener) => voidRegisters an event listener on the native input element for a given event.
deregisterInputInteractionHandler(evtType: string, handler: EventListener) => voidDeregisters an event listener on the native input element for a given event.
registerValidationAttributeChangeHandler(handler: (attributeNames: string[]) => void) => MutationObserverRegisters a validation attribute change listener on the input element. Handler accepts list of attribute changes.
deregisterValidationAttributeChangeHandler(!MutationObserver) => voidDisconnects a validation attribute observer on the input element.
getNativeInput() => NativeInputType | nullReturns an object representing the native text input element, with a similar API shape. See types.ts.
isFocused() => booleanReturns whether the input is focused.
shakeLabel(shouldShake: boolean) => voidShakes the label to indicate an invalid input value.
floatLabel(shouldFloat: boolean) => voidFloats the label.
hasLabel() => booleanDetermines whether the text field has a label element.
getLabelWidth() => numberReturns the width of the label element in px.
activateLineRipple() => voidActivates the text field's line ripple sub-element.
deactivateLineRipple() => voidDeactivate the text field's line ripple sub-element.
setLineRippleTransformOrigin(normalizedX: number) => voidSets the CSS transform-origin property to the given value on the text field's line ripple sub-element (if present).
hasOutline() => booleanDetermines whether the text field has an outline sub-element.
notchOutline(labelWidth: number) => voidSets the width of the text field's notched outline sub-element.
closeOutline() => voidCloses the text field's notched outline sub-element.
MDCTextFieldAdapter.getNativeInput()

Returns an object representing the native text input element, with a similar API shape. We never alter the value within our code, however we do update the disabled property, so if you choose to duck-type the return value for this method in your implementation it's important to keep this in mind. Also note that this method can return null, which the foundation will handle gracefully.

MDCTextFieldAdapter.getIdleOutlineStyleValue(propertyName: string)

Returns the idle outline element's computed style value of the given css property propertyName. The vanilla implementation achieves this via getComputedStyle(...).getPropertyValue(propertyName).

MDCTextFieldFoundation

PropertyValue TypeDescription
shouldFloatboolean (read-only)Determines whether the label should float.
shouldShakeboolean (read-only)Determines whether the label should shake.
Method SignatureDescription
getValue() => stringReturns the input's value.
setValue(value: string)Sets the input's value.
setUseNativeValidation(useNativeValidation: boolean)Sets whether to check native HTML validity state (true, default) or custom validity state when updating styles (false).
setValid(isValid: boolean)Sets custom validity and updates styles accordingly. Note that native validation will still be honored subsequently unless setUseNativeValidation(false) is also called.
isValid() => booleanReturns the component's current validity state (either native or custom, depending on how setUseNativeValidation() was configured).
isDisabled() => booleanReturns whether or not the input is disabled.
setDisabled(disabled: boolean) => voidUpdates the input's disabled state.
handleTextFieldInteraction(evt: Event) => voidHandles click and keydown events originating from inside the Text Field component.
handleInput() => voidHandles text input and textarea input event.
handleValidationAttributeChange(attributesList: !Array<string>) => voidHandles validation attribute changes.
activateFocus() => voidActivates the focus state of the Text Field. Normally called in response to the input focus event.
deactivateFocus() => voidDeactivates the focus state of the Text Field. Normally called in response to the input blur event.
setHelperTextContent(content: string) => voidSets the content of the helper text.
setLeadingIconAriaLabel(label: string) => voidSets the aria label of the leading icon.
setLeadingIconContent(content: string) => voidSets the text content of the leading icon.
setTrailingIconAriaLabel(label: string) => voidSets the aria label of the trailing icon.
setTrailingIconContent(content: string) => voidSets the text content of the trailing icon.
notchOutline(openNotch: boolean) => voidOpens/closes the notched outline.
setTransformOrigin(evt: TouchEvent | MouseEvent) => voidSets the line ripple's transform origin, so that the line ripple activate animation will animate out from the user's click location.
autoCompleteFocus() => voidActivates the Text Field's focus state in cases when the input value is changed programmatically (i.e., without user action).
setAutovalidate(shouldAutovalidate: boolean) => voidSets whether or not the textfield should validate its input when value changes.
getAutovalidate() => booleanWhether or not the textfield should validate its input when value changes. true by default.

MDCTextFieldFoundation supports multiple optional sub-elements: helper text and icon. The foundations of these sub-elements must be passed in as constructor arguments to MDCTextFieldFoundation.

Keywords

FAQs

Package last updated on 28 Apr 2022

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc