Checkbox
Examples
Checked
Indeterminate
Disabled
Sizes
Help Text
Custom Validity
Slots
Properties
Events
Methods
Parts
Dependencies

Checkbox

<sl-checkbox> | SlCheckbox

Since 2.0

stable

Checkboxes allow the user to toggle an option on or off.

Checkbox

<sl-checkbox>Checkbox</sl-checkbox>

This component works with standard <form> elements. Please refer to the section on form controls to learn more about form submission and client-side validation.

Examples

Checked

Use the checked attribute to activate the checkbox.

Checked

<sl-checkbox checked>Checked</sl-checkbox>

Indeterminate

Use the indeterminate attribute to make the checkbox indeterminate.

Indeterminate

<sl-checkbox indeterminate>Indeterminate</sl-checkbox>

Disabled

Use the disabled attribute to disable the checkbox.

Disabled

<sl-checkbox disabled>Disabled</sl-checkbox>

Sizes

Use the size attribute to change a checkbox’s size.

Small

Medium

Large

<sl-checkbox size="small">Small</sl-checkbox>
<br />
<sl-checkbox size="medium">Medium</sl-checkbox>
<br />
<sl-checkbox size="large">Large</sl-checkbox>

Help Text

Add descriptive help text to a switch with the help-text attribute. For help texts that contain HTML, use the help-text slot instead.

Label

<sl-checkbox help-text="What should the user know about the checkbox?">Label</sl-checkbox>

Custom Validity

Use the setCustomValidity() method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.

<form class="custom-validity">
  <sl-checkbox>Check me</sl-checkbox>
  <br />
  <sl-button type="submit" variant="primary" style="margin-top: 1rem;">Submit</sl-button>
</form>
<script>
  const form = document.querySelector('.custom-validity');
  const checkbox = form.querySelector('sl-checkbox');
  const errorMessage = `Don't forget to check me!`;

  // Set initial validity as soon as the element is defined
  customElements.whenDefined('sl-checkbox').then(async () => {
    await checkbox.updateComplete;
    checkbox.setCustomValidity(errorMessage);
  });

  // Update validity on change
  checkbox.addEventListener('sl-change', () => {
    checkbox.setCustomValidity(checkbox.checked ? '' : errorMessage);
  });

  // Handle submit
  form.addEventListener('submit', event => {
    event.preventDefault();
    alert('All fields are valid!');
  });
</script>

Slots

Name	Description
(default)	The checkbox’s label.
`help-text`	Text that describes how to use the checkbox. Alternatively, you can use the `help-text` attribute.

Learn more about using slots.

Properties

Name	Description	Type	Default
`stacked`	Whether the label should always be stacked	`boolean`	`false`
`name`	The name of the checkbox, submitted as a name/value pair with form data.	`string`	`''`
`value`	The current value of the checkbox, submitted as a name/value pair with form data.	`string`	-
`size`	The checkbox’s size.	`'small' \| 'medium' \| 'large'`	`'medium'`
`disabled`	Disables the checkbox.	`boolean`	`false`
`checked`	Draws the checkbox in a checked state.	`boolean`	`false`
`indeterminate`	Draws the checkbox in an indeterminate state. This is usually applied to checkboxes that represents a “select all/none” behavior when associated checkboxes have a mix of checked and unchecked states.	`boolean`	`false`
`defaultChecked`	The default value of the form control. Primarily used for resetting the form control.	`boolean`	`false`
`form`	By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you to place the form control outside of a form and associate it with the form that has this `id`. The form must be in the same document or shadow root for this to work.	`string`	`''`
`required`	Makes the checkbox a required field.	`boolean`	`false`
`helpText` `help-text`	The checkbox’s help text. If you need to display HTML, use the `help-text` slot instead.	`string`	`''`
`validity`	Gets the validity state object	-	-
`validationMessage`	Gets the validation message	-	-
`updateComplete`	A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name	Description	Event Detail
`sl-blur`	Emitted when the checkbox loses focus.	-
`sl-change`	Emitted when the checked state changes.	-
`sl-focus`	Emitted when the checkbox gains focus.	-
`sl-input`	Emitted when the checkbox receives input.	-
`sl-invalid`	Emitted when the form control has been checked for validity and its constraints aren’t satisfied.	-

Learn more about events.

Methods

Name	Description	Arguments
`click()`	Simulates a click on the checkbox.	-
`focus()`	Sets focus on the checkbox.	`options: FocusOptions`
`blur()`	Removes focus from the checkbox.	-
`checkValidity()`	Checks for validity but does not show a validation message. Returns `true` when valid and `false` when invalid.	-
`getForm()`	Gets the associated form, if one exists.	-
`reportValidity()`	Checks for validity and shows the browser’s validation message if the control is invalid.	-
`setCustomValidity()`	Sets a custom validation message. The value provided will be shown to the user when the form is submitted. To clear the custom validation message, call this method with an empty string.	`message: string`

Learn more about methods.

Parts

Name	Description
`base`	The component’s base wrapper.
`control`	The square container that wraps the checkbox’s checked state.
`control--checked`	Matches the control part when the checkbox is checked.
`control--indeterminate`	Matches the control part when the checkbox is indeterminate.
`checked-icon`	The checked icon, an `<sl-icon>` element.
`indeterminate-icon`	The indeterminate icon, an `<sl-icon>` element.
`label`	The container that wraps the checkbox’s label.
`form-control-help-text`	The help text’s wrapper.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

<sl-icon>