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>
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
Attribute | Property | Reflect | Type | Default |
---|---|---|---|---|
variant | variant | 'filled' | 'outlined' | 'filled' | |
Defines the text field style. Default is
| ||||
type | type | 'text' | 'number' | 'password' | 'url' | 'email' | 'search' | 'tel' | 'hidden' | 'date' | 'datetime-local' | 'month' | 'time' | 'week' | 'text' | |
Specifies the text field type. Default is
| ||||
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 | ||||
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 | ||||
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 | ||||
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 | ||||
icon | icon | string | - | |
Material Icons name for the prefix icon of the text field. Alternatively, use | ||||
end-icon | endIcon | string | - | |
Material Icons name for the suffix icon of the text field. Alternatively, use | ||||
error-icon | errorIcon | string | - | |
Material Icons name displayed on the right side of the text field when the form field validation fails. Alternatively, use | ||||
form | form | string | - | |
Associates the text field with a This attribute allows text field elements to be associated with | ||||
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 | ||||
max-rows | maxRows | number | - | |
The maximum number of rows when | ||||
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 | ||||
min | min | number | - | |
The minimum value when | ||||
max | max | number | - | |
The maximum value when | ||||
step | step | number | - | |
The step interval during increment and decrement when | ||||
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 | ||||
show-password-icon | showPasswordIcon | string | - | |
Material Icons name for the visible password toggle button. Alternatively, use | ||||
hide-password-icon | hidePasswordIcon | string | - | |
Material Icons name for the hidden password toggle button. Alternatively, use | ||||
autocapitalize | autocapitalize | 'none' | 'sentences' | 'words' | 'characters' | - | |
A non-standard iOS attribute for automatic capitalization. Possible values:
| ||||
autocorrect | autocorrect | string | - | |
The | ||||
autocomplete | autocomplete | 'off' | 'on' | - | |
Enables the browser's autocomplete feature for text input. Possible values:
| ||||
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:
| ||||
spellcheck | spellcheck | boolean | false | |
Enable spell checking. | ||||
inputmode | inputmode | 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url' | - | |
Customizes the virtual keyboard. Possible values:
| ||||
validity | ValidityState | - | ||
A | ||||
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 | ||||
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 |
| void |
Selects a specific range in the text field. | ||
setRangeText |
| 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 | ||
reportValidity | boolean | |
Checks the validity of the form field. If it's invalid, it triggers an | ||
setCustomValidity |
| 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 |
| void |
Sets focus on the element. An optional parameter can be an object with a | ||
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 |
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 |
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. |