Since Shoelace 2.0 Code stable Pattern stable Figma ready

Checkbox

<sl-checkbox> | SlCheckbox

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

Examples

Basic Checkbox

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

sl-checkbox Checkbox

import SlCheckbox from '@teamshares/shoelace/dist/react/checkbox';

const App = () => <SlCheckbox>Checkbox</SlCheckbox>;

Checked

Use the checked attribute to activate the checkbox.

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

sl-checkbox checked="true" Checked

import SlCheckbox from '@teamshares/shoelace/dist/react/checkbox';

const App = () => <SlCheckbox checked>Checked</SlCheckbox>;

Indeterminate

Use the indeterminate attribute to make the checkbox indeterminate.

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

sl-checkbox indeterminate="true" Indeterminate

import SlCheckbox from '@teamshares/shoelace/dist/react/checkbox';

const App = () => <SlCheckbox indeterminate>Indeterminate</SlCheckbox>;

Disabled

Use the disabled attribute to disable the checkbox.

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

sl-checkbox disabled="true" Disabled

import SlCheckbox from '@teamshares/shoelace/dist/react/checkbox';

const App = () => <SlCheckbox disabled>Disabled</SlCheckbox>;

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>

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

import SlCheckbox from '@teamshares/shoelace/dist/react/checkbox';

const App = () => (
  <>
    <SlCheckbox size="small">Small</SlCheckbox>
    <br />
    <SlCheckbox size="medium">Medium</SlCheckbox>
    <br />
    <SlCheckbox size="large">Large</SlCheckbox>
  </>
);

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>

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

import SlCheckbox from '@shoelace-style/shoelace/dist/react/checkbox';

const App = () => <SlCheckbox help-text="What should the user know about the switch?">Label</SlCheckbox>;

Contained

Use the contained attribute to add a container around the checkbox.

Checkbox Disabled Checked
A short description about this option
 
<sl-checkbox contained style="width: 100%;"> Checkbox </sl-checkbox>
<sl-checkbox contained disabled style="width: 100%;"> Disabled </sl-checkbox>
<sl-checkbox contained checked style="width: 100%;">
  Checked
  <div slot="help-text">A short description about this option</div>
</sl-checkbox>

  sl-checkbox contained="true" style="width: 100%;" Checked
  sl-checkbox contained="true" disabled="true" style="width: 100%;" Disabled
  sl-checkbox contained="true" checked="true" style="width: 100%;"
    | Checked
    div slot="help-text" A short description about this option

import { SlRadio } from '@teamshares/shoelace/dist/react';
const App = () => (
  <>
    <SlCheckbox contained style="width: 100%;">
      Checked
    </SlCheckbox>
    <SlCheckbox contained disabled style="width: 100%;">
      Disabled
    </SlCheckbox>
    <SlCheckbox contained checked style="width: 100%;">
      Checked
      <div slot="help-text">A short description about this option</div>
    </SlCheckbox>
  </>
);

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.

Check me
Submit 
<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 = `Do not 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>

form.custom-validity
  sl-checkbox Check me
  br
  sl-button type="submit" variant="primary" style="margin-top: 1rem;" Submit

javascript:
  const form = document.querySelector(.custom-validity);
  const checkbox = form.querySelector(sl-checkbox);
  const errorMessage = `Do not forget to check me!`;

  // Set initial validity as soon as the element is defined
  customElements.whenDefined(sl-checkbox).then(() => {
    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!);
  });

import { useEffect, useRef } from 'react';
import SlButton from '@teamshares/shoelace/dist/react/button';
import SlCheckbox from '@teamshares/shoelace/dist/react/checkbox';

const App = () => {
  const checkbox = useRef(null);
  const errorMessage = `Do not forget to check me!`;

  function handleChange() {
    checkbox.current.setCustomValidity(checkbox.current.checked ? '' : errorMessage);
  }

  function handleSubmit(event) {
    event.preventDefault();
    alert('All fields are valid!');
  }

  useEffect(() => {
    checkbox.current.setCustomValidity(errorMessage);
  }, []);

  return (
    <form class="custom-validity" onSubmit={handleSubmit}>
      <SlCheckbox ref={checkbox} onSlChange={handleChange}>
        Check me
      </SlCheckbox>
      <br />
      <SlButton type="submit" variant="primary" style={{ marginTop: '1rem' }}>
        Submit
      </SlButton>
    </form>
  );
};

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.1.0/cdn/components/checkbox/checkbox.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.1.0/cdn/components/checkbox/checkbox.js';

To import this component using a bundler: 

import '@shoelace-style/shoelace/dist/components/checkbox/checkbox.js';

To import this component as a React component: 

import SlCheckbox from '@shoelace-style/shoelace/dist/react/checkbox';

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 Reflects Type Default
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
contained Draws a container around the checkbox. 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 React Event Description Event Detail
sl-blur onSlBlur Emitted when the checkbox loses focus. -
sl-change onSlChange Emitted when the checked state changes. -
sl-focus onSlFocus Emitted when the checkbox gains focus. -
sl-input onSlInput Emitted when the checkbox receives input. -
sl-invalid onSlInvalid 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>