mirror of https://github.com/material-components/material-web.git synced 2024-11-11 06:10:17 +03:00

Elizabeth Mitchell a8ce2ab427 docs: fix broken theming links

PiperOrigin-RevId: 564410908

2023-09-11 09:32:57 -07:00

13 KiB

Raw Blame History

Text field

This documentation is fully rendered on the Material Web catalog

Text fields let users enter text into a UI.

Design article
API Documentation (coming soon)
Source code

Usage

Text fields behave like <input> elements. They provide a container with labels for user input.

<md-filled-text-field label="Label" value="Value"></md-filled-text-field>

<md-outlined-text-field label="Label" value="Value"></md-outlined-text-field>

Input type

A text field's type attribute changes how the text field works, such as displaying a different keyboard or providing default validation.

<md-filled-text-field label="Username" type="email"></md-filled-text-field>
<md-filled-text-field label="Password" type="password"></md-filled-text-field>

Tip: use the inputmode attribute for more control over the displayed keyboard.

Labels

Text fields should label their value with a floating label, a placeholder, or an external label. Labels help the user understand what value to input.

<md-outlined-text-field label="Favorite food"></md-outlined-text-field>

<md-outlined-text-field placeholder="email@domain.com"></md-outlined-text-field>

<div>First name</div>
<md-outlined-text-field aria-label="First name"></md-outlined-text-field>

Note: text fields do not currently support aria-labelledby. External labels must provide an aria-label. See b/276484803.

Textarea

Multi-line text fields behave like <textarea> elements.

Textareas can specify the initial number of rows. Use CSS width, height, and resize to control the resize behavior of a textarea.

<style>
  md-filled-text-field {
    resize: vertical;
  }
</style>
<md-filled-text-field type="textarea" label="Vertical resize" rows="3"></md-filled-text-field>

Icons

Text fields may display optional icons. Use icons to describe the input method (such as a search icon), provide additional functionality (such as a clear icon), or to express errors.

<md-outlined-text-field placeholder="Search for messages">
  <md-icon slot="leading-icon">search</md-icon>
</md-outlined-text-field>

<md-outlined-text-field label="Password" type="password">
  <md-icon-button toggle slot="trailing-icon">
    <md-icon>visibility</md-icon>
    <md-icon slot="selected">visibility_off</md-icon>
  </md-icon-button>
</md-outlined-text-field>

<md-outlined-text-field label="Username" error error-text="Username not available">
  <md-icon slot="trailing-icon">error</md-icon>
</md-outlined-text-field>

Prefix and suffix

Add prefix-text and suffix-text attributes to text fields to display additional context for the value.

<md-outlined-text-field label="Dollar amount" type="number"
    value="0" prefix-text="$" suffix-text=".00"></md-outlined-text-field>

Supporting text

Supporting text conveys additional information about the input field, such as how it will be used. Supporting text can be replaced with error text when validating.

<md-filled-text-field label="Comments"
    supporting-text="Provide comments for the issue"></md-filled-text-field>

<md-filled-text-field label="Name" required
    supporting-text="*required"
    error-text="Please fill out this field"></md-filled-text-field>

Character counter

Text fields with a maxlength attribute will display a character counter.

<md-outlined-text-field label="Title" value="Short" maxlength="10"></md-outlined-text-field>

Validation

Text fields that validate can use constraint validation or manual validation.

Constraint validation

Text fields may validate using the browser's constraint validation API. Each input type above links to an article that describes how to validate it.

Text fields in a <form> will validate on submission, or by calling textField.reportValidity().

<form>
  <md-filled-text-field name="name" label="Name"
      required></md-filled-text-field>
  <md-filled-text-field name="email" label="Email"
      pattern="[\w\d-]+" suffix-text="@gmail.com"></md-filled-text-field>
</form>

Use the following properties and methods to check and report validation errors.

validity is the text field's current ValidityState.
setCustomValidity() sets a custom error message.
checkValidity() dispatches an invalid event.
reportValidity() dispatches an invalid event and displays the error in the text field's supporting text.

Manual validation

Alternatively, text fields can manually control their error state and error message. Use manual validation if the text fields are driven by application state logic.

<md-outlined-text-field label="Username" value="jdoe"
    error error-text="Username is not available"></md-outlined-text-field>

Tip: Prefer constraint validation when possible for more platform features, such as <form> validation and listening to invalid events.

Accessibility

Add an aria-label attribute to text fields with external labels or text fields whose labels need to be more descriptive.

<div>Username</div>
<md-filled-text-field aria-label="Username"></md-filled-text-field>

<md-filled-text-field label="First" aria-label="First name"></md-filled-text-field>

Filled text field

Filled and outlined text fields are functionally identical. See choosing a text field for guidance on which one to use.

<md-filled-text-field label="Filled" value="Value"></md-filled-text-field>

Outlined text field