MDUIDocsEnglish简体中文LightDarkSystem
Preset Colors
Custom Color
Extract Color from Wallpaper
Select a Wallpaper
Getting Started
Styles
Frameworks
Components
Avatar Badge BottomAppBar Button ButtonIcon Card Checkbox Chip CircularProgress Collapse Dialog Divider Dropdown Fab Icon Layout LinearProgress List Menu NavigationBar NavigationDrawer NavigationRail Radio RangeSlider Select SegmentedButton Slider Snackbar Switch Tabs TextField Tooltip TopAppBar
Functions
Libraries

TextField

Text fields, typically used in forms and dialogs, allow users to input text.

Usage

Import the component:

import 'mdui/components/text-field.js';

Import the TypeScript type:

import type { TextField } from 'mdui/components/text-field.js';

Example:

<mdui-text-field label="Text Field"></mdui-text-field>

Examples

Variant

The variant attribute modifies the shape of the text field.

Helper Text

The label attribute sets the label text above the text field.

The placeholder attribute sets the placeholder text when there is no value.

The helper attribute or helper slot sets the helper text at the bottom of the text field. To display the helper text only when the input is focused, use the helper-on-focus attribute.

Clearable

The clearable attribute adds a clear button on the right when the text field has a value.

End-Aligned Text

The end-aligned attribute aligns the text to the right.

Prefix, Suffix, Icons

The icon and end-icon attributes or slots add Material Icons to the left and right of the text field, respectively.

The prefix and suffix attributes or slots add text to the left and right of the text field. This text is displayed only when the text field is focused or has a value.

Readonly

The readonly attribute makes the text field read-only.

Disabled

The disabled attribute disables the text field.

Multi-line Text Field

The rows attribute sets the number of rows for a multi-line text field.

To automatically adjust the height of the text field based on the length of the input, use the autosize attribute. The min-rows and max-rows attributes specify the minimum and maximum number of rows.

Character Counter

The maxlength attribute sets the maximum number of characters for the text field. To display a character counter below the text field, use the counter attribute.

Password Field

For password fields (type="password"), the toggle-password attribute adds a button on the right to toggle the visibility of the password.

API

Properties

AttributePropertyReflectTypeDefault
variantvariant'filled' | 'outlined''filled'

Defines the text field style. Default is filled. Possible values:

  • filled: Text field with background color, providing a stronger visual effect.
  • outlined: Text field with border, providing a subtler visual effect.
typetype'text' | 'number' | 'password' | 'url' | 'email' | 'search' | 'tel' | 'hidden' | 'date' | 'datetime-local' | 'month' | 'time' | 'week''text'

Specifies the text field type. Default is text. Possible values:

  • text: Standard text field.
  • number: Allows only numeric input. Devices with dynamic keyboards will display a numeric keyboard.
  • password: Masks the input for password confidentiality.
  • url: Validates URL format. Devices with dynamic keyboards will display a URL-specific keyboard.
  • email: Validates email format. Devices with dynamic keyboards will display an email-specific keyboard.
  • search: Changes the enter icon to a search icon on devices with dynamic keyboards.
  • tel: Displays a phone number keyboard on devices with dynamic keyboards.
  • hidden: Hides the control, but its value will still be submitted to the server.
  • date: Activates a date picker or a numeric scroll wheel for year, month, and day in supported browsers.
  • datetime-local: Activates a date and time picker in supported browsers, excluding time zone.
  • month: Allows input for year and month, excluding time zone.
  • time: Allows time input, excluding time zone.
  • week: Allows input for dates consisting of a year and week, excluding time zone.
namenamestring''

The name of text field, which is submitted with form data.

valuevaluestring''

The value of text field, which is submitted with form data.

defaultValuestring''

The default value. The text field resets to this value on form reset. This can only be set via the JavaScript property.

labellabelstring-

Label text.

placeholderplaceholderstring-

Placeholder text.

helperhelperstring-

The helper text displayed at the bottom of the text field. Alternatively, use slot="helper".

helper-on-focushelperOnFocusbooleanfalse

If set, the helper text is only displayed when the text field is focused.

clearableclearablebooleanfalse

If set, the text field can be cleared.

clear-iconclearIconstring-

Material Icons name displayed on the right when the text field is clearable. Alternatively, use slot="clear-icon".

end-alignedendAlignedbooleanfalse

Aligns the text to the right.

prefixprefixstring-

The prefix text for the text field. It is only displayed when the text field is focused or has a value. Alternatively, use slot="prefix".

suffixsuffixstring-

The suffix text for the text field. It is only displayed when the text field is focused or has a value. Alternatively, use slot="suffix".

iconiconstring-

Material Icons name for the prefix icon of the text field. Alternatively, use slot="icon".

end-iconendIconstring-

Material Icons name for the suffix icon of the text field. Alternatively, use slot="end-icon".

error-iconerrorIconstring-

Material Icons name displayed on the right side of the text field when the form field validation fails. Alternatively, use slot="error-icon".

formformstring-

Associates the text field with a <form> element. The value should be the id of a <form> in the same document. If not set, the text field is associated with its parent <form>, if any.

This attribute allows text field elements to be associated with <form>s anywhere in the document, not just inside a <form>.

readonlyreadonlybooleanfalse

Makes the text field read-only.

disableddisabledbooleanfalse

Disables the text field.

requiredrequiredbooleanfalse

The field must be filled in before the form is submitted.

rowsrowsnumber-

The number of rows in the text field.

autosizeautosizebooleanfalse

Allows the text field height to adjust automatically based on the input content.

min-rowsminRowsnumber-

The minimum number of rows when autosize is enabled.

max-rowsmaxRowsnumber-

The maximum number of rows when autosize is enabled.

minlengthminlengthnumber-

The minimum number of characters for input.

maxlengthmaxlengthnumber-

The maximum number of characters for input.

countercounterbooleanfalse

Displays the character count when maxlength is specified.

minminnumber-

The minimum value when type is number.

maxmaxnumber-

The maximum value when type is number.

stepstepnumber-

The step interval during increment and decrement when type is number.

patternpatternstring-

The regular expression for form validation.

toggle-passwordtogglePasswordbooleanfalse

Adds a toggle button for showing and hiding the password when type is password.

show-password-iconshowPasswordIconstring-

Material Icons name for the visible password toggle button. Alternatively, use slot="show-password-icon".

hide-password-iconhidePasswordIconstring-

Material Icons name for the hidden password toggle button. Alternatively, use slot="hide-password-icon".

autocapitalizeautocapitalize'none' | 'sentences' | 'words' | 'characters'-

A non-standard iOS attribute for automatic capitalization. Possible values:

  • none: Disables automatic capitalization.
  • sentences: Capitalizes the first letter of each sentence.
  • words: Capitalizes the first letter of each word.
  • characters: Capitalizes all letters.
autocorrectautocorrectstring-

The autocorrect attribute of the input element.

autocompleteautocomplete'off' | 'on'-

Enables the browser's autocomplete feature for text input. Possible values:

  • off: Disables browser autocomplete.
  • on: Enables browser autocomplete.
enterkeyhintenterkeyhint'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send'-

Customizes the Enter key text or icon on the virtual keyboard. The effect varies based on the device and language. Possible values:

  • enter: Inserts a new line, typically used in a multi-line text field.
  • done: Indicates input completion, closes the virtual keyboard.
  • go: Navigates to the target of the entered text.
  • next: Moves to the next text field.
  • previous: Moves to the previous text field.
  • search: Navigates to search results.
  • send: Sends a text message.
spellcheckspellcheckbooleanfalse

Enable spell checking.

inputmodeinputmode'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url'-

Customizes the virtual keyboard. Possible values:

  • none: No virtual keyboard. This is useful for custom input controls.
  • text: Standard text input keyboard.
  • decimal: Decimal input keyboard. This includes a period . or comma , and numbers.
  • numeric: Numeric keyboard. This displays numbers 0-9.
  • tel: Phone number keyboard. This includes numbers 0-9, asterisk *, and hash # keys.
  • search: Search-optimized virtual keyboard. 'Search' is displayed on the submit button.
  • email: Email-optimized virtual keyboard. This typically includes @ ..
  • url: URL-optimized virtual keyboard. This typically includes . / #.
validityValidityState-

A ValidityState object that represents the element's validity states.

validationMessagestring-

The element's validation message. This is empty if the element meets its constraints.

valueAsNumbernumber-

Gets or sets the value as a number. Returns NaN if the value cannot be converted.

autofocusautofocusbooleanfalse

Determines if the element should be focused when the page loads.

tabindextabIndexnumber-

Specifies the order in which the element receives focus when navigating with the Tab key.

Methods

NameParametersReturns
select
void

Selects the content of the text field.

setSelectionRange
  • start: number
  • end: number
  • direction: 'forward' | 'backward' | 'none'
void

Selects a specific range in the text field.

setRangeText
  • replacement: string
  • start: number
  • end: number
  • selectMode: 'select' | 'start' | 'end' | 'preserve'
void

Replaces a specific range in the text field with new text.

checkValidity
boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.

reportValidity
boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.

setCustomValidity
  • message: string
void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.

click
void

Simulates a mouse click on the element.

focus
  • options: FocusOptions (Optional)
void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.

blur
void

Removes focus from the element.

Events

Name
focus

Emitted when the text field gains focus.

blur

Emitted when the text field loses focus.

change

Emitted when the value changes and the text field loses focus.

input

Emitted when the value changes.

invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.

clear

Emitted when clear button is clicked. Can be prevented with event.preventDefault().

Slots

Name
icon

Icon on the left side.

end-icon

Icon on the right side.

error-icon

Icon on the right side for validation failure.

prefix

Text on the left side.

suffix

Text on the right side.

clear-button

Clear button.

clear-icon

Icon in the clear button.

toggle-password-button

Button to toggle password visibility.

show-password-icon

Icon in the password visibility toggle button (show password state).

hide-password-icon

Icon in the password visibility toggle button (hide password state).

helper

Text at the bottom for help.

CSS Parts

Name
container

Container for the text field.

icon

Icon on the left side.

end-icon

Icon on the right side.

error-icon

Icon on the right side for validation failure.

prefix

Text on the left side.

suffix

Text on the right side.

label

Label text above the field.

input

Internal <input> or <textarea> element.

clear-button

Clear button.

clear-icon

Icon in the clear button.

toggle-password-button

Button to toggle password visibility.

show-password-icon

Icon in the password visibility toggle button (show password state).

hide-password-icon

Icon in the password visibility toggle button (hide password state).

supporting

Container for bottom supporting info, including helper, error, and counter.

helper

Text at the bottom for help.

error

Text at the bottom for error.

counter

Character count in the bottom right corner.

On this page