Text field
A text field component allows users to enter and edit single-line textual input. It serves as a fundamental building block for various form inputs in user interfaces
<sl-text-field id="first-name" value="John" aria-label="First name"></sl-text-field>
When to use
The following guidance describes when to use the text field component.
Unique input
When users need to input information that is unique and cannot be anticipated from a predefined set of options. Text fields provide the flexibility to capture diverse and unpredictable data.
Single-line input
Text fields are ideal for capturing single-line responses.
When not to use
Text fields may not be the best choice in the following scenarios:
Sensitive information
For handling sensitive or confidential information, such as passwords or credit card numbers, it's advisable to utilize specialized secure input fields designed to obscure the entered data for enhanced security.
Longer text responses
Consider using a text area when you anticipate the input length will exceed the width of a text field or when you encourage users to provide longer text responses.
Anatomy
Item | Name | Description | Optional |
---|---|---|---|
1 | Container | An input container is a structured enclosure for user input elements. It facilitates organized and user-friendly data collection in interfaces. | no |
2 | Input & Placeholder text | Input text, entered by users, and placeholder text, providing guidance or examples. | yes |
3 | Validation icon | Ensures input accuracy for users. | yes |
Figma Options
With these options you can tweak the appearance of the text field in Figma. They are available in the Design Panel so you can compose the text field to exactly fit the user experience need for the uses case you are working on.
Item | Options | Description |
---|---|---|
Size | md lg | The text field is available in two sizes. If not specified the default value is md (medium). |
Variant | default valid invalid | When you're working on a scenario where you show what happens when a field is skipped or filled in incorrectly you can choose a different variant to show this. |
State | idle hover active disabled | These states are applied automatically in interactive examples or can be set explicitly when the use case asks for it. Default value is idle . |
Placeholder | boolean | If the setting is enabled, the placeholder will be visible, whereas if it is disabled, the user's input will be displayed. Default value is off . |
Placeholder text | value | Use placeholder text to give the user a short hint about what they need to input (e.g. a sample value or a short description of the expected format). Placeholder is not a replacement for labels. It's an optional feature that disappears once users begin entering their data. |
Hint | boolean | To turn to hint on or off. Default value is off . |
Input Text | value | Will be shown as the value of the text field |
Label | value | Provide users with additional context about button functionality by adding a label, ensuring clarity and ease of use. |
Focus ring | boolean | Turn the focus ring option to show the focus state of the text field. Default value is off . |
<sl-text-field id="last-name" aria-label="Last name" value="Smith"></sl-text-field>
API
Component has a range of properties to define the experience in different use cases.
Properties
Name | Attribute | Type | Default | Description |
---|---|---|---|---|
autocomplete | autocomplete | typeof HTMLInputElement.prototype.autocomplete | undefined | Specifies which type of data the browser can use to pre-fill the input. | |
customValidity | custom-validity | string | undefined | The error message to display when the control is invalid. | |
dirty | - | boolean | false | A control is dirty if the user has changed the value in the UI. |
disabled | disabled | boolean | undefined | Whether the text field is disabled; when set no interaction is possible. | |
form | - | HTMLFormElement | null | The form associated with the control. | |
formValue | - | unknown | The value used when submitting the form. | |
input | - | HTMLInputElement | The input element in the light DOM. | |
inputSize | input-size | number | undefined | The size attribute of the input element. | |
labels | - | `NodeListOf<HTMLLabelElement>` | null | The labels associated with the control. | |
maxLength | maxlength | number | undefined | Maximum length (number of characters). | |
minLength | minlength | number | undefined | Minimum length (number of characters). | |
name | name | string | undefined | The name of the form control. | |
nativeFormValue | - | FormValue | Returns the form value as used in a native `<form>`. This is always a string, File, FormData or null. | |
pattern | pattern | string | undefined | This will validate the value of the input using the given pattern. | |
placeholder | placeholder | string | undefined | Placeholder text in the input. | |
rawValue | - | string | '' | The raw (string) value of the input. |
readonly | readonly | boolean | undefined | Whether you can interact with the input or if it is just a static, readonly display. | |
required | required | boolean | undefined | Whether the text field is a required field. | |
showValid | show-valid | boolean | false | When set will cause the control to show it is valid after reportValidity is called. |
showValidity | show-validity | 'valid' | 'invalid' | undefined | Whether to show the validity state. | |
size | size | 'md' | 'lg' | 'md' | The size of the input. |
touched | - | boolean | false | A control is marked touched once the user has triggered a blur event on it. |
type | type | 'email' | 'number' | 'tel' | 'text' | 'url' | 'password' | 'text' | The input type. Only text types are valid here. For other types, see their respective components. |
valid | - | boolean | Returns whether the form control is valid or not. | |
validationMessage | - | string | String representing a localized (by the browser) message that describes the validation constraints that the control does not satisfy (if any). The string is empty if the control is not a candidate for constraint validation, or it satisfies its constraints. For true localization, see `getLocalizedValidationMessage()` instead. | |
validity | - | ValidityState | Returns the validity state the control is in. | |
validityState | - | 'valid' | 'invalid' | 'pending' | Returns the current validity state. | |
value | value | unknown | undefined | The value of the text field. |
Methods
Name | Parameters | Return | Description |
---|---|---|---|
renderPrefix | TemplateResult | typeof nothing | Renders the prefix slot; can be overridden to customize the prefix. | |
renderInputSlot | TemplateResult | Render the input slot; separate method so it is composable for child components. | |
renderSuffix | TemplateResult | typeof nothing | Renders the suffix slot; can be overridden to customize the suffix. | |
getLocalizedValidationMessage | string | This returns a localized validation message. It does not support all `ValidityState` properties, since some require more context than we have here. If you need to support more, you can override this method in your own form control. | |
parseValue | value: string | T | undefined | Method that converts the string value in the input to the specified type T. Override this method if you want to convert the value in a different way. Throw an error if the value is invalid. |
formatValue | value?: T | string | Method that formats the value and set's it on the native input element. Override this method if you want to format the value in a different way. |
reportValidity | boolean | Returns whether the control is valid. If the control is invalid, calling this will also cause an `invalid` event to be dispatched. After calling this, the control will also report the validity to the user. | |
setCustomValidity | message: string | Promise<string> | void | Sets a custom validation message for the form control. If the message is not an empty string, that will make the control invalid. By setting it to an empty string again, you can make the control valid again. |
Events
Name | Event type | Description |
---|---|---|
sl-blur | SlBlurEvent | Emits when the focus leaves the component. |
sl-change | SlChangeEvent<T | undefined> | Emits when the value changes. |
sl-focus | SlFocusEvent | Emits when the component gains focus. |
sl-form-control | SlFormControlEvent | Emits when the form control is added to the DOM. |
sl-update-state | SlUpdateStateEvent | Emits when the UI state (dirty, pristine, touched or untouched) of the form control changes. |
sl-update-validity | SlUpdateValidityEvent | Emits when the validity of the form control changes. |
sl-validate | SlValidateEvent | Emits when the form control can be validated. |
Slots
Name | Description |
---|---|
prefix | Content shown before the input |
input | The slot for the input element |
suffix | Content shown after the input |
CSS Parts
Name | Description |
---|---|
wrapper | The input's wrapper |
Keyboard interactions
Here's an overview of the common keyboard interactions associated with a text field:
Command | Description |
---|---|
Tab | When focus is outside the text field, moves focus to the input container. If focus is on the input container, moves focus to the end enhancer (if provided, and interactive). |
WAI-ARIA
WAI-ARIA Roles, States, and Properties for a text field provide essential information to assistive technologies and screen readers. They convey the text field's role, state, and additional properties to ensure accessibility and a better user experience for individuals using assistive technology.
Attribute | Value | Description | User supplied |
---|---|---|---|
role | 'textbox' | Identifies as a text input | no |
aria-label | string | Defines a string that labels the action that will be performed when the user interacts with the text field. Needs to be added when the text-field is not wrapped with sl-form-field and there is no sl-label . | yes |
aria-labelledby | string | Used to connect with single header/element that describes the text field, when there is no label component connected to. | yes |
aria-required | boolean | Informs the user that an element is required. When set to ‘true’, screen readers notify users that the element is required. | yes |
aria-disabled | boolean | Announces the text field component as disabled with a screen reader. See [Note 1] below. | yes |
Notes:
- The
aria-disabled
should not be used as a one-for-one replacement for thedisabled
attribute because they have different functionalities:
disabled
dims the text field visually, takes it out of the tab-focus sequence, prevents actions (click, enter) on it and announces it as 'dimmed' or 'disabled' in a screen reader.aria-disabled
only does the latter. You will need to disable the functionality yourself. This might be useful for scenarios where you don't want to take the text field out of the navigation flow.
When disabled
is added to a text field there is no need to also add aria-disabled
. Everything aria-disabled
does, disabled
does as well. You can read more on the difference and in which scenarios which option might be preferable on the MDN page about aria-disabled.