Form

When to use

The form component should be used whenever you have a form that needs to be filled out by a user. The form component is a container for form fields.

When not to use

Do not use the form component if you only have one form field. Usually this indicates a specific usage of a form control, and that it should be used on its own.

Related components

• Form field

The <sl-form> component fulfills four functions:

1. It provides a default layout for form fields.
2. It manages the way required/optional fields should be marked.
3. It provides a way to validate all form fields at once.
4. It allows you to query the state of the form.

Layout

By default, the form component has a vertical flexbox layout. This means that form fields will stack on top of each other. If you want to change this, you can customize the CSS to use a grid layout instead.

/* Define a two column grid layout. */
sl-form {
  display: grid;
  gap: 1rem;
  grid-template-columns: 1fr 1fr;
}

/* Position the form fields in specific columns here... */

/* Make the button bar span both columns. */
sl-button-bar {
  grid-column: 1 / 3;
}

Required or optional

The form itself manages a mark state. This determines how required or optional labels should be shown. If the required fields outnumber the optional fields, only the optional fields will be marked. If it is the other way around, then only the required fields will be marked.

This behavior happens automatically, and the developer does not need to do anything to make it work.

Validation

The form component provides a way to validate all form fields at once. The reportValidity() method can be used to trigger validation on all form fields. This method returns a boolean indicating whether the form is valid or not.

submitButton.addEventListener('click', event => {
  const form = event.target.closest('sl-form');

  if (form?.reportValidity()) {
    // Submit the form
  }
});

State

You can query the state of the entire form by simply getting the valid property on the <sl-form>. This will return false if any form field within the form is not valid.

Validate on blur

By default, validation feedback is only shown after reportValidity() is called (for example on form submit). You can opt in to validation on blur by adding the validate-on-blur attribute to <sl-form>:

<sl-form validate-on-blur>
  <!-- form fields -->
</sl-form>

With this enabled, each field is validated when the user leaves it. For required fields, this behavior is designed with accessibility in mind:

• Just tabbing through a field shows no error. This allows keyboard and screen reader users to explore the form and hear all field labels and hints without being interrupted by error announcements on empty fields they haven't interacted with yet.
• Typing and clearing a field, then leaving it, shows the required error on blur. The user has interacted with the field and is expected to see feedback.
• Mouse actions such as unchecking a checkbox or removing the last selection in a combobox do not show the error immediately; the error is shown when the control loses focus (for example by clicking outside the field).

Fields that were never interacted with are still validated when reportValidity() is called, for example on submit.

Validation triggers per field type

API

Form component is meant as a wrapper around form fields.

Properties

Methods

Events

Keyboard interactions

Here's an overview of the common keyboard interactions associated with a form:

Validation announcements

By default, <sl-form> announces field validation errors through the live region helper. If your form also shows an aggregated error summary (with sl-inline-message), set announce-errors="false" on <sl-form> to avoid duplicate announcements.