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

Usage

Code

Accessibility

  <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:

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

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.Specifies whether the attribute is always set in the component (no) or it can be provided by the developer (yes)

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 the disabled 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.

Interactive example