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>

<br/><br/>

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

Source

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>

Source

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>

Source

API

Properties

Attribute	Property	Type	Default
`variant`	`variant`	`'filled' \| 'outlined'`	`'filled'`
Defines the text field variant. Default is `filled`. Possible values: `filled`: Text field with a background color for stronger visual emphasis. `outlined`: Text field with a border for subtler visual emphasis.
`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 numeric input only. Virtual keyboards on mobile devices show a numeric layout. `password`: Hides the password as you type. `url`: Validates URL format. Virtual keyboards on mobile devices show a URL-specific layout. `email`: Validates email format. Virtual keyboards on mobile devices show an email-specific layout. `search`: Shows a search icon on the Enter key in virtual keyboards. `tel`: Displays a phone keypad on virtual keyboards. `hidden`: Hides the control, but its value is still submitted to the server. `date`: Opens 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, without a time zone. `month`: Allows entering a year and month without a time zone. `time`: Allows time input without a time zone. `week`: Allows entering a year and week without a time zone.
`name`	`name`	`string`	`''`
The name of the text field, which is submitted with form data.
`value`	`value`	`string`	`''`
The value of the text field, which is submitted with form data.
	`defaultValue`	`string`	`''`
The default value. The text field resets to this value on form reset. JavaScript only.
`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`
Shows the helper text only when the text field is focused.
`clearable`	`clearable`	`boolean`	`false`
Makes the text field clearable.
`clear-icon`	`clearIcon`	`string`	-
Material Icons name shown 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 form field validation fails. Alternatively, use `slot="error-icon"`.
`form`	`form`	`string`	-
Associates the text field with a `<form>` element. Set this to the `id` of a `<form>` in the same document. If omitted, the text field uses its parent `<form>`, if any. This lets the text field work with any form in the document, not just the one it is nested in.
`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 out before the form is submitted.
`rows`	`rows`	`number`	-
The number of rows in the text field.
`autosize`	`autosize`	`boolean`	`false`
Automatically adjusts the height of the text field based on its 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 for increment/decrement when `type` is `number`.
`pattern`	`pattern`	`string`	-
The regular expression for form validation.
`toggle-password`	`togglePassword`	`boolean`	`false`
Adds a toggle button to show or hide 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`	`string`	-
The `autocomplete` attribute of the `input` element.
`enterkeyhint`	`enterkeyhint`	`'enter' \| 'done' \| 'go' \| 'next' \| 'previous' \| 'search' \| 'send'`	-
Customizes the Enter key text or icon on the virtual keyboard. The effect varies by device and language. Possible values: `enter`: Inserts a new line, typically used in a multi-line text field. `done`: Indicates completion and 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`
Enables spell checking.
`inputmode`	`inputmode`	`'none' \| 'text' \| 'decimal' \| 'numeric' \| 'tel' \| 'search' \| 'email' \| 'url'`	-
Customizes the virtual keyboard. Possible values: `none`: No virtual keyboard. 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' appears on the submit button. `email`: Email-optimized virtual keyboard. This typically includes `@` and `.`. `url`: URL-optimized virtual keyboard. This typically includes `.`, `/`, and `#`.
	`validity`	`ValidityState`	-
A `ValidityState` object that represents the element's validity states.
	`validationMessage`	`string`	-
Validation message. Empty string when valid.
	`valueAsNumber`	`number`	-
Gets or sets the value as a `number`. Returns `NaN` if the value cannot be converted.
`autofocus`	`autofocus`	`boolean`	`false`
Whether the element is focused when the page loads.
`tabindex`	`tabIndex`	`number`	-
The element's tab order 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 is invalid, it triggers an `invalid` event and returns `false`. If valid, it returns `true`.
`reportValidity`		`boolean`
Checks the validity of the form field. If it is invalid, it triggers an `invalid` event, returns `false`, and displays a validation message. If valid, it returns `true`.
`setCustomValidity`	`message: string`	`void`
Sets a custom error message. If the message is non-empty, the field is considered invalid.
`click`		`void`
Simulates a mouse click on the element.
`focus`	`options: FocusOptions` (Optional)	`void`
Sets focus on the element. An optional object parameter may include 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 does not meet the constraints.
`clear`
Emitted when the 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`
Helper text shown below the field.

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 supporting text at the bottom of the field, including helper, error, and counter.
`helper`
Helper text shown below the field.
`error`
Text at the bottom for error.
`counter`
Character count in the bottom right corner.

Tabs

Tooltip

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