Form

A wrapper component for forms

Usage

Code

Accessibility

Mathematics

Geography

Physics

History

Cancel

Create course

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

  <sl-form-field label="Subjects">
    <sl-checkbox-group name="subjects">
      <sl-checkbox>Mathematics</sl-checkbox>
      <sl-checkbox>Geography</sl-checkbox>
      <sl-checkbox>Physics</sl-checkbox>
      <sl-checkbox>History</sl-checkbox>
    </sl-checkbox-group>
  </sl-form-field>

  <sl-button-bar align="end">
    <sl-button fill="outline">Cancel</sl-button>
    <sl-button variant="primary">Create course</sl-button>
  </sl-button-bar>
</sl-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.

Form field

The <sl-form> component fulfills four functions:

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

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
  }
});

Name	Attribute	Type	Default	Description
`controls`	-	`Array<HTMLElement & FormControl>`	`[]`	The controls in the form; not necessarily the same amount as the fields.
`dirty`	-	`boolean`		A form is marked dirty when the user has modified a form control.
`disabled`	`disabled`	`boolean \| undefined`		Will disable the entire form when true.
`fields`	-	`FormField[]`	`[]`	The fields in the form.
`invalid`	-	`boolean`		Whether the form is invalid.
`pristine`	-	`boolean`		A form is marked pristine as long as the user hasn't modified anything in the form.
`resetEvent`	-	`EventEmitter<SlResetEvent>`
`showValidity`	-	`boolean`		Indicates whether to show validity state.
`touched`	-	`boolean`		A form is marked touched once the user has triggered a blur event on a form control.
`untouched`	-	`boolean`		A form is marked untouched as long as the user hasn't trigger a blur event on a form control.
`valid`	-	`boolean`		Whether the form is valid.
`value`	-	`T`		The aggregated value of all form controls.

Methods

Name	Return	Description
`reportValidity`	`boolean`	Calls `reportValidity()` on all form controls and returns if they are all valid.
`requestSubmit`	`void`	If the form is valid, it will emit an `sl-submit` event.
`reset`	`void`	Puts all the initial values of the form controls back and updates the validity of all fields.

Events

Name	Event type	Description
`sl-reset`	`SlResetEvent`	Emits when the form has been reset.
`sl-submit`	`SlSubmitEvent`	Emits when the form is to be submitted.

Keyboard interactions

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

Command	Description
Tab	When focus is outside the form, moves focus to the first form field.

Interactive example