Form field

A wrapper component for form controls

Usage

Code

Accessibility

<sl-form-field hint="Please enter a descriptive name for the course." label="Course name">
  <sl-text-field name="courseName"></sl-text-field>
</sl-form-field>

When to use

If a field is part of a larger form, you should wrap it in a form field component. This will ensure that the field is properly labeled and that the hint is announced to screen readers.

When not to use

Do not use the form field if the field is not part of a larger form. For example, if you are using a text field as a search input, you should not wrap it in a form field.

A form field always has a vertical layout. The label is always at the top, followed by an optional hint and then the form control itself, and at the bottom the error message, depending on the state of the component.

Anatomy

A form field should always have a label. That label can be hidden from view, but it should always be present in the DOM. The label is used to associate the form field with the form control. The label is also used to announce the form field to screen readers. The hint is optional. It is used to provide additional information about the form field. The hint is announced to screen readers after the label.

Item	Name	Description	Optional
1	Form field	Wrapper component for form controls.	no
2	Label	Descriptive text that helps identify and describe the purpose of the form control.	no
3	Hint	Provides additional information or context.	yes
4	Form control	Space to insert the preferred form control.	no
4	Validation message	Describes what went wrong after validation.	yes

Figma Options

With these options you can tweak the appearance of the label and hint in Figma. They are available in the Design Panel so you can compose the input field to exactly fit the user experience need for the uses case you are working on.

Label

Item	Options	Description
Size	`sm` `md` `lg`	The label is available in three sizes. If not specified the default value is `medium`.
Text	`value`	Displays the text of the label.
Disabled	`boolean`	Indicates if the label has disabled styling.
Required	`boolean`	Indicates if the form control is required.
Optional	`boolean`	Indicates if the form control is optional.
Info	`boolean`	Shows an info icon on the end of the label to provide additional information.

Hint

Item	Options	Description
Size	`sm` `md` `lg`	The hint is available in three sizes. If not specified the default value is `medium`.
Text	`value`	Displays the text of the hint.
State	`default` `invalid` `disabled`	Indicates the state of the form control.
Icon	`boolean`	Show an icon in front of the hint.

Form

The <sl-form-field> component fulfills four functions:

It is a layout container for a form control.
It provides label and hint ease-of-use properties.
It displays any validation messages from the form control.
It manages integration within a parent <sl-form> component.

Layout

The form field component always has a vertical layout. The label is always at the top, followed by the form control itself and at the bottom an optional hint or error message.

The styling of the form field is managed by design tokens and should not be changed manually.

Label and hint

Both label and hint are available as attributes or properties.

<sl-form-field label="My label" hint="Hint text">
  ...
</sl-form-field>

If you need more control over the contents of the label or hint, the form field component provides label and hint slots. If you use the <sl-label> or <sl-hint> component, then that slot will automatically be applied.

<sl-form-field>
  <sl-label>This is a <em>custom</em> label.</sl-label>
  <sl-hint>This is a <strong>custom</strong> hint</sl-hint>
  ...
</sl-form-field>

Validation messages

The form field component listens for sl-update-validity events from the form control. When the form control is invalid, the form field will display the validationMessage. When the form control is valid, the form field will hide the error message.

The API tries to closely follow the native ValidityState API. The validationMessage property is a string that contains the error message. The validity property is an object that contains the validation state properties.

You can set a custom validity by calling the setCustomValidity(message) method on the form control. This will trigger the sl-update-validity event on the form control.

The reportValidity() method can be called on the form field to trigger validation on the form control. This method returns a boolean indicating whether the form control is valid or not. Normally you would not call this method directly, but instead call it on the parent <sl-form> component.

Integration

Besides delegating the reportValidity() calls from the parent <sl-form> to the form control, the form field also registers itself with the parent <sl-form>. This allows the <sl-form> to keep track of all the form fields and their validity. This done by dispatching the sl-form-field event for which the <sl-form> listens.

API

Form field component provides a wrapper around a form control with a label, help text, and error messages.

Properties

Name	Attribute	Type	Description
`control`	-	`HTMLElement & FormControl \| undefined`	The form control element.
`hint`	`hint`	`string \| undefined`	A hint that will be shown when there are no validation messages. You can also slot an `<sl-hint>` element.
`label`	`label`	`string \| undefined`	The text for the label. You can also slot an `<sl-label>` element.
`mark`	`mark`	`'optional' \| 'required' \| undefined`	How to mark this field depending if it is required or not.

Events

Name	Event type	Description
`sl-form-field`	`SlFormFieldEvent`	Emits when the field is added to a form.