14.0.0 • Published 4 months ago

@material/textfield v14.0.0

Weekly downloads
63,172
License
MIT
Repository
github
Last release
4 months ago

Text Field

Text fields allow users to input, edit, and select text.

Design & API Documentation

Installation

npm install @material/textfield

Usage

HTML Structure

<div class="mdc-text-field">
  <input type="text" id="my-text-field" class="mdc-text-field__input">
  <label class="mdc-floating-label" for="my-text-field">Hint text</label>
  <div class="mdc-line-ripple"></div>
</div>

Input Types

Text field supports text and password input types (e.g., <input type="password" class="mdc-text-field__input">).

Other input types (such as number and date) are not currently supported.

HTML5 Validation

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

<div class="mdc-text-field">
  <input type="password" id="pw" class="mdc-text-field__input" required minlength=8>
  <label for="pw" class="mdc-floating-label">Password</label>
  <div class="mdc-line-ripple"></div>
</div>

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-floating-label with the mdc-floating-label--float-above modifier class, and mdc-text-field with the mdc-text-field--upgraded 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).

<div class="mdc-text-field mdc-text-field--upgraded">
  <input type="text" id="pre-filled" class="mdc-text-field__input" value="Pre-filled value">
  <label class="mdc-floating-label mdc-floating-label--float-above" for="pre-filled">
    Label in correct place
  </label>
  <div class="mdc-line-ripple"></div>
</div>

Full Width

Full width text fields are useful for in-depth tasks or entering complex information.

<div class="mdc-text-field mdc-text-field--fullwidth">
  <input class="mdc-text-field__input"
         type="text"
         placeholder="Full-Width Text Field"
         aria-label="Full-Width Text Field">
</div>

NOTE: Do not use mdc-text-field--box or mdc-text-field--outlined to style a full width text field.

NOTE: Do not use mdc-floating-label within mdc-text-field--fullwidth. Labels should not be included as part of the DOM structure of a full width text field.

Textarea

<div class="mdc-text-field mdc-text-field--textarea">
  <textarea id="textarea" class="mdc-text-field__input" rows="8" cols="40"></textarea>
  <label for="textarea" class="mdc-floating-label">Textarea Label</label>
</div>

Disabled

Add the disabled attribute to <input> if the mdc-text-field is disabled. You also need to add mdc-text-field--disabled to the mdc-text-field.

<div class="mdc-text-field mdc-text-field--disabled">
  <input type="text" id="disabled-text-field" class="mdc-text-field__input" disabled>
  <label class="mdc-floating-label" for="disabled-text-field">Disabled text field</label>
  <div class="mdc-line-ripple"></div>
</div>

Outlined

<div class="mdc-text-field mdc-text-field--outlined">
  <input type="text" id="tf-outlined" class="mdc-text-field__input">
  <label for="tf-outlined" class="mdc-floating-label">Your Name</label>
  <div class="mdc-notched-outline">
    <svg>
      <path class="mdc-notched-outline__path"/>
    </svg>
  </div>
  <div class="mdc-notched-outline__idle"></div>
</div>

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

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

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. See here for more information on using helper text.

Leading and Trailing Icons

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

CSS Classes

CSS ClassDescription
mdc-text-fieldMandatory
mdc-text-field--upgradedIndicates the text field is upgraded, normally by JavaScript
mdc-text-field--boxStyles the text field as a box text field
mdc-text-field--outlinedStyles the text field as an outlined text field
mdc-text-field--fullwidthStyles the text field as a full width 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--denseStyles the text field as a dense 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

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 Text Field Box

MixinDescription
mdc-text-field-box-corner-radius($radius)Customizes the border radius for the text field box variant.
mdc-text-field-box-fill-color($color)Customizes the background color of the text field box.

Mixins for Text Field Outline

MixinDescription
mdc-text-field-focused-outline-color($color)Customizes the outline border color when the text field is focused.
mdc-text-field-hover-outline-color($color)Customizes the outline border color when the text field is hovered.
mdc-text-field-outline-color($color)Customizes the border color of the outline text field.
mdc-text-field-outline-corner-radius($radius)Sets the border radius of of the text field outline variant.

Mixins for Textarea

MixinDescription
mdc-text-field-textarea-corner-radius($radius)Customizes the border radius for a <textarea> variant.
mdc-text-field-textarea-fill-color($color)Customizes the color of the background of the textarea.
mdc-text-field-textarea-stroke-color($color)Customizes the color of the border of the textarea.

Mixins for Text Field Fullwidth

MixinDescription
mdc-text-field-fullwidth-bottom-line-color($color)Customizes the fullwidth text field variant bottom line color.

Other Mixins

MixinDescription
mdc-text-field-bottom-line-color($color)Customizes the text field bottom line color except the outline and textarea variants.
mdc-text-field-hover-bottom-line-color($color)Customizes the hover text field bottom line color except the outline and textarea variants.
mdc-text-field-ink-color($color)Customizes the text entered into the text field.
mdc-text-field-label-color($color)Customizes the text color of the label.
mdc-text-field-line-ripple-color($color)Customizes the color of the default line ripple of the text field.

MDCTextField

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

PropertyValue TypeDescription
valueStringProxies to the foundation's getValue/setValue methods.
disabledBooleanProxies to the foundation's isDisabled/setDisabled methods.
validBooleanProxies to the foundation's isValid/setValid methods.
requiredBooleanProxies to the foundation's isRequired/setRequired methods.
helperTextContentStringProxies to the foundation's setHelperTextContent method when set
rippleMDCRippleThe MDCRipple instance for the root element that MDCTextField initializes; this only applies to Text Field Box, and is null for other variants
Method SignatureDescription
layout() => voidAdjusts the dimensions and positions for all sub-elements

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
getNativeInput() => {value: string, disabled: boolean, badInput: boolean, checkValidity: () => boolean}?Returns an object representing the native text input element, with a similar API shape
isFocused() => booleanReturns whether the input is focused
isRtl() => booleanReturns whether the direction of the root element is set to RTL
hasOutline() => booleanReturns whether there is an outline element
notchOutline(labelWidth: number, isRtl: boolean) => voidUpdates the outline path to open the notch and update the notch width for the label element
closeOutline() => voidCloses the notch in the outline element

MDCTextFieldAdapter.getNativeInput()

Returns an object representing the native text input element, with a similar API shape. The object returned should include the value, disabled and badInput properties, as well as the checkValidity() function. 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

Method SignatureDescription
getValue() => stringReturns the input's value.
setValue(value: string)Sets the input's value.
isValid() => booleanIf a custom validity is set, returns that value. Otherwise, returns the result of native validity checks.
setValid(isValid: boolean)Sets custom validity. Once set, native validity checking is ignored.
isDisabled() => booleanReturns whether or not the input is disabled
setDisabled(disabled: boolean) => voidUpdates the input's disabled state
isRequired() => booleanReturns whether the input is required.
setRequired(isRequired: boolean)Sets whether the input is required.
handleTextFieldInteraction(evt: Event) => voidHandles click and keydown events originating from inside the Text Field component
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.
notchOutline(openNotch: boolean) => voidOpens/closes the notched outline.

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.

democensa@material/mwc-textfieldzagenzagen-production@lhixson/component-library@mcfirm/mwc-textfield@zentek/textfieldpwa-test-hpwa-test1pwa-test2sot-incubatormdwrapper@beezydev/textfieldcensapackagedesignsystemindesigndocumentabcdesignabcsystempackagestorypackagedesignopenstamanagertest-component-library-stencilmaterial-components-web@everything-registry/sub-chunk-584@arterial/textfield@authentic/mwc-textfield@aurelia2-mdc-web/text-field@aurelia-mdc-web/text-field@defense-unicorns/unicorn-ui@bitchin/react-material-web@bringhub/fabric.jsselective-editzarinpal-story-bookvoyager-componentsvue-material-design-componentstransposed-gridvue-compostwalletscore-reportwebcontainer4uui-componentsvegatrosvelte-arcadiasvelte-toolboxsvmdsyderal-materialstencil-todo-listtest-rsmdctest-stencil-to-react-componentssariska-cobrowsingsariska-webapp@detachhead/smui-textfield@codeadraas/vue3-material@hieunv/react-mdc@dolphin-kiss/material-wc-textfield@dhruval/dk-input@dreamworld/dw-input@angular/material@angular/material-experimental@emuanalytics/flow-rdf@infinitebrahmanuniverse/nolb-_mate@inovex.de/elements@dev.mohe/mwc-textfield@gmvdev/materials@leanup/material-core@mcwv/textfield@mhamrah/svelte-material-ui@material/react-text-field@mdc-stencil/textfield@materialr/textfield@materials-elements/core@materials-elements/site@materials-ui/core@materials-ui/site@o-rango/orango-material-design@photon-elements/photon-ide-elements@xolvio/plate-ui-commentsaapp-chat.jseasyfyv3-presentationdepsmdc-react-gumballmdc-101-web@xdam/ember-partials@pitaya-components/text-field@pitaya-components/textfield@simplus/siui@sme.up/ketchup@smui/textfieldmaple-material-vue@types/material__textfieldember-material-components@vue-cruder/uiember-cli-mdc-textfieldfrt-mth-webcomponents@preact-material-components/textfield@pojagi/hoquet@openremote/or-input@pmwcs/textfield@react-mdc/textfield@plonquo/ember-material-components@react-universal-dialogs/android@robertkern/vue-material@rmwc/text-field
14.0.0

2 years ago

13.0.0

3 years ago

12.0.0

3 years ago

11.0.0

3 years ago

10.0.0

3 years ago

9.0.0

3 years ago

8.0.0

3 years ago

7.0.0

4 years ago

6.0.0

4 years ago

5.1.0

4 years ago

5.0.0

4 years ago

4.0.0

4 years ago

3.2.0

5 years ago

4.0.0-canary.1

5 years ago

4.0.0-canary.0

5 years ago

4.0.0-alpha.0

5 years ago

3.1.0

5 years ago

3.1.0-alpha.0

5 years ago

3.0.0

5 years ago

3.0.0-alpha.1

5 years ago

3.0.0-alpha.0

5 years ago

2.3.1

5 years ago

2.3.0

5 years ago

2.1.1

5 years ago

2.1.0

5 years ago

2.0.0

5 years ago

1.1.1

5 years ago

1.1.0

5 years ago

1.0.1

5 years ago

1.0.0

5 years ago

1.0.0-1

5 years ago

1.0.0-0

5 years ago

0.44.1

5 years ago

0.44.0

5 years ago

0.43.1

5 years ago

0.43.0

5 years ago

0.42.1

5 years ago

0.42.0

5 years ago

0.41.0

5 years ago

0.40.1

5 years ago

0.40.0

6 years ago

0.39.3

6 years ago

0.39.2

6 years ago

0.39.1

6 years ago

0.39.0

6 years ago

0.39.0-0

6 years ago

0.38.1

6 years ago

0.38.0

6 years ago

0.37.1

6 years ago

0.37.0

6 years ago

0.36.1

6 years ago

0.36.0

6 years ago

0.36.0-0

6 years ago

0.35.2

6 years ago

0.35.1

6 years ago

0.35.0

6 years ago

0.34.1

6 years ago

0.34.0

6 years ago

0.33.0

6 years ago

0.32.0

6 years ago

0.31.0

6 years ago

0.30.0

6 years ago

0.29.0

6 years ago

0.28.0

6 years ago

0.27.0

6 years ago

0.26.0

6 years ago

0.25.0

6 years ago

0.24.0

6 years ago

0.23.0

6 years ago

0.5.0

6 years ago

0.4.1

7 years ago

0.4.0

7 years ago

0.3.6

7 years ago

0.3.5

7 years ago

0.3.4

7 years ago

0.3.3

7 years ago

0.3.2

7 years ago

0.3.1

7 years ago

0.3.0

7 years ago

0.2.11

7 years ago

0.2.10

7 years ago

0.2.9

7 years ago

0.2.8

7 years ago

0.2.7

7 years ago

0.2.6

7 years ago

0.2.5

7 years ago

0.2.4

7 years ago

0.2.3

7 years ago

0.2.2

7 years ago

0.2.1

7 years ago

0.2.0

7 years ago

0.1.1

7 years ago

0.1.0

7 years ago