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>

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.

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

<mdui-text-field autosize min-rows="2" max-rows="5" label="Text Field"></mdui-text-field>

Code

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.

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

Code

Password Field

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

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

Code

API

Properties

Attribute	Property	Type	Default
`variant`	`variant`	`'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.
`type`	`type`	`'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.
`name`	`name`	`string`	`''`
The name of text field, which is submitted with form data.
`value`	`value`	`string`	`''`
The value of text field, which is submitted with form data.
	`defaultValue`	`string`	`''`
The default value. The text field resets to this value on form reset. This can only be set via the JavaScript property.
`label`	`label`	`string`	-
Label text.
`placeholder`	`placeholder`	`string`	-
Placeholder text.
`helper`	`helper`	`string`	-
The helper text displayed at the bottom of the text field. Alternatively, use `slot="helper"`.
`helper-on-focus`	`helperOnFocus`	`boolean`	`false`
If set, the helper text is only displayed when the text field is focused.
`clearable`	`clearable`	`boolean`	`false`
If set, the text field can be cleared.
`clear-icon`	`clearIcon`	`string`	-
Material Icons name displayed on the right when the text field is clearable. Alternatively, use `slot="clear-icon"`.
`end-aligned`	`endAligned`	`boolean`	`false`
Aligns the text to the right.
`prefix`	`prefix`	`string`	-
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"`.
`suffix`	`suffix`	`string`	-
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"`.
`icon`	`icon`	`string`	-
Material Icons name for the prefix icon of the text field. Alternatively, use `slot="icon"`.
`end-icon`	`endIcon`	`string`	-
Material Icons name for the suffix icon of the text field. Alternatively, use `slot="end-icon"`.
`error-icon`	`errorIcon`	`string`	-
Material Icons name displayed on the right side of the text field when the form field validation fails. Alternatively, use `slot="error-icon"`.
`form`	`form`	`string`	-
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>`.
`readonly`	`readonly`	`boolean`	`false`
Makes the text field read-only.
`disabled`	`disabled`	`boolean`	`false`
Disables the text field.
`required`	`required`	`boolean`	`false`
The field must be filled in before the form is submitted.
`rows`	`rows`	`number`	-
The number of rows in the text field.
`autosize`	`autosize`	`boolean`	`false`
Allows the text field height to adjust automatically based on the input content.
`min-rows`	`minRows`	`number`	-
The minimum number of rows when `autosize` is enabled.
`max-rows`	`maxRows`	`number`	-
The maximum number of rows when `autosize` is enabled.
`minlength`	`minlength`	`number`	-
The minimum number of characters for input.
`maxlength`	`maxlength`	`number`	-
The maximum number of characters for input.
`counter`	`counter`	`boolean`	`false`
Displays the character count when `maxlength` is specified.
`min`	`min`	`number`	-
The minimum value when `type` is `number`.
`max`	`max`	`number`	-
The maximum value when `type` is `number`.
`step`	`step`	`number`	-
The step interval during increment and decrement when `type` is `number`.
`pattern`	`pattern`	`string`	-
The regular expression for form validation.
`toggle-password`	`togglePassword`	`boolean`	`false`
Adds a toggle button for showing and hiding the password when `type` is `password`.
`show-password-icon`	`showPasswordIcon`	`string`	-
Material Icons name for the visible password toggle button. Alternatively, use `slot="show-password-icon"`.
`hide-password-icon`	`hidePasswordIcon`	`string`	-
Material Icons name for the hidden password toggle button. Alternatively, use `slot="hide-password-icon"`.
`autocapitalize`	`autocapitalize`	`'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.
`autocorrect`	`autocorrect`	`string`	-
The `autocorrect` attribute of the `input` element.
`autocomplete`	`autocomplete`	`'off' \| 'on'`	-
Enables the browser's autocomplete feature for text input. Possible values: `off`: Disables browser autocomplete. `on`: Enables browser autocomplete.
`enterkeyhint`	`enterkeyhint`	`'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.
`spellcheck`	`spellcheck`	`boolean`	`false`
Enable spell checking.
`inputmode`	`inputmode`	`'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 `. / #`.
	`validity`	`ValidityState`	-
A `ValidityState` object that represents the element's validity states.
	`validationMessage`	`string`	-
The element's validation message. This is empty if the element meets its constraints.
	`valueAsNumber`	`number`	-
Gets or sets the value as a `number`. Returns `NaN` if the value cannot be converted.
`autofocus`	`autofocus`	`boolean`	`false`
Determines if the element should be focused when the page loads.
`tabindex`	`tabIndex`	`number`	-
Specifies the order in which the element receives focus when navigating with the Tab key.

Methods

Name	Parameters	Returns
`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.

Select

Up Next

LinearProgress

TextField

Usage

Examples

Variant

Helper Text

Clearable

End-Aligned Text

Prefix, Suffix, Icons

Readonly

Disabled

Multi-line Text Field

Character Counter

Password Field

API

Properties

Methods

Events

Slots

CSS Parts