Checkbox

<quiet-checkbox>

stable

since 1.0

Checkboxes let users select one or more options from a list or toggle single options on and off.

I will feed the cats

<quiet-checkbox name="feed" value="yes">I will feed the cats</quiet-checkbox>

Examples Jump to heading

Checked initially Jump to heading

Add the checked attribute to check the checkbox initially.

I will feed the cats

<quiet-checkbox name="feed" value="yes" checked>I will feed the cats</quiet-checkbox>

Filled checkboxes Jump to heading

Set the appearance attribute to filled to change the checkbox's appearance.

Filled checkbox

<quiet-checkbox appearance="filled">Filled checkbox</quiet-checkbox>

Changing the size Jump to heading

Use the size attribute to change the checkbox's size.

              Extra small

              Small

              Medium

              Large

              Extra large

<quiet-checkbox size="xs">Extra small</quiet-checkbox><br>
<quiet-checkbox size="sm">Small</quiet-checkbox><br>
<quiet-checkbox size="md">Medium</quiet-checkbox><br>
<quiet-checkbox size="lg">Large</quiet-checkbox><br>
<quiet-checkbox size="xl">Extra large</quiet-checkbox>

Indeterminate Jump to heading

Use the indeterminate attribute to put the checkbox in an indeterminate state. This can be used to show a mixed selection in a group of "child" checkboxes.

Indeterminate

<quiet-checkbox indeterminate>Indeterminate</quiet-checkbox>

Disabling Jump to heading

Use the disabled attribute to disable the checkbox.

              Unchecked and disabled

              Checked and disabled

              Indeterminate and disabled

<quiet-checkbox disabled>Unchecked and disabled</quiet-checkbox><br>
<quiet-checkbox checked disabled>Checked and disabled</quiet-checkbox><br>
<quiet-checkbox indeterminate disabled>Indeterminate and disabled</quiet-checkbox>

Validation Jump to heading

The required attribute can be applied to enable validation using the Constraint Validation API. This will prevent form submission until the checkbox is checked.

              
                I will feed the cats
                
                Submit
                Reset

<form action="about:blank" method="get" target="_blank">
  <quiet-checkbox name="feed" value="yes" required>I will feed the cats</quiet-checkbox>
  <br><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

Using custom validation Jump to heading

Use the custom-validity attribute to make the checkbox invalid and show a custom error message on submit. This will override all other validation parameters. To clear the error, remove the attribute or set it to an empty string.

              
                I will feed the cats
                
                Submit
                Reset

<form action="about:blank" method="get" target="_blank">
  <quiet-checkbox name="feed" value="yes" required custom-validity="Not so fast, bubba!">I will feed the cats</quiet-checkbox>
  <br><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

Most validation attributes work exactly like their native counterparts. However, the custom-validity attribute is offered in lieu of the setCustomValidity() method. This allows you to declaratively set custom errors instead of having to call a method with JavaScript.

Styling validation Jump to heading

You can style valid and invalid checkboxes using the :valid and :invalid pseudo classes.

              
                I will feed the cats
                
                Submit
                Reset

<form action="about:blank" method="get" target="_blank" class="checkbox__validation-pseudo">
  <quiet-checkbox name="feed" value="yes" required>I will feed the cats</quiet-checkbox>
  <br><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .checkbox__validation-pseudo {
    quiet-checkbox:valid {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-checkbox:invalid {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

However, these selectors will match even before the user has had a chance to fill out the form. More often than not, you'll want to use the user-valid and user-invalid custom states instead. This way, validation styles are only shown after the user interacts with the form control or when the form is submitted.

              
                I will feed the cats
                
                Submit
                Reset

<form action="about:blank" method="get" target="_blank" class="checkbox__validation-custom">
  <quiet-checkbox name="feed" value="yes" required>I will feed the cats</quiet-checkbox>
  <br><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .checkbox__validation-custom {
    quiet-checkbox:state(user-valid) {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-checkbox:state(user-invalid) {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

Styling checkboxes Jump to heading

Checkboxes come with a simple, minimal appearance. Feel free to customize them with your own styles. Here's a quick way to turn a checkbox into a selectable tile.

              
                Basketball
              
                Football
              
                Ping-pong

<quiet-checkbox checked class="checkbox__tile">
  <quiet-icon name="ball-basketball"></quiet-icon>
  <span>Basketball</span>
</quiet-checkbox>

<quiet-checkbox class="checkbox__tile">
  <quiet-icon name="ball-american-football"></quiet-icon>
  <span>Football</span>
</quiet-checkbox>

<quiet-checkbox class="checkbox__tile">
  <quiet-icon name="ping-pong"></quiet-icon>
  <span>Ping-pong</span>
</quiet-checkbox>

<style>
  .checkbox__tile {
    position: relative;
    border: solid 1px var(--quiet-neutral-stroke-soft);
    border-radius: var(--quiet-border-radius);
    box-shadow: var(--quiet-shadow-softer);

    &::part(label) {
      display: flex;
      flex-direction: column;
      gap: .5rem;
      padding: 2rem 1.5rem .5rem 1.5rem;
    }

    &::part(visual-box) {
      position: absolute;
      top: 0.5rem;
      left: 0.5rem;
    }

    quiet-icon {
      font-size: 4rem;
      stroke-width: .75px;
    }

    span {
      font-size: .875rem;
      color: var(--quiet-primary-text-on-soft);
    }

    &:state(checked) {
      background-color: var(--quiet-primary-fill-softer);
      border-color: var(--quiet-primary-stroke-mid);
    }
  }
</style>

A gray kitten plays with a blue toy mouse

A gray kitten practices prowling on a brown floor

A gray kitten looks at the camera from behind a tree

<quiet-checkbox checked class="checkbox__image">
  <img draggable="false" src="https://images.unsplash.com/photo-1620196244888-d31ff5bbf163?q=80&w=400&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" alt="A gray kitten plays with a blue toy mouse">
</quiet-checkbox>

<quiet-checkbox class="checkbox__image">
  <img draggable="false" src="https://images.unsplash.com/photo-1597239351814-a5f03b4663c0?q=80&w=400&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" alt="A gray kitten practices prowling on a brown floor">
</quiet-checkbox>

<quiet-checkbox class="checkbox__image">
  <img draggable="false" src="https://images.unsplash.com/photo-1503844281047-cf42eade5ca5?q=80&w=400&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" alt="A gray kitten looks at the camera from behind a tree">
</quiet-checkbox>

<style>
  .checkbox__image {
    isolation: isolate;
    position: relative;
    
    img {
      display: block;
      width: 150px;
      height: 150px;
      object-fit: cover;
      border-radius: .25rem;
    }

    &::part(visual-box) {
      position: absolute;
      bottom: .5rem;
      left: .5rem;
      width: 1.5rem;
      height: 1.5rem;
      border: none;
      background-color: color-mix(in oklab, black, transparent 50%);
    }

    &:state(checked)::part(visual-box) {
      background-color: var(--quiet-primary-fill-mid);
    }

    &::part(check-icon) {
      scale: .75;
    }
  }
</style>

It's not recommended to hide the checkbox unless your styles make it very clear to users that the control is checkable.

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN

npm

To manually import <quiet-checkbox> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet@1.0.0/dist/components/checkbox/checkbox.js';

To manually import <quiet-checkbox> from npm, use the following code.

import '@quietui/quiet/dist/components/checkbox/checkbox.js';

Slots Jump to heading

Checkbox supports the following slots. Learn more about using slots

Name	Description
(default)	The checkbox's label. For plain-text labels, you can use the `label` attribute instead.

Properties Jump to heading

Checkbox has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute	Description	Type	Default
`associatedForm`	A reference to the `<form>` associated with the form control, or `null` if no form is associated.	`HTMLFormElement null`	`null`
`label`	The checkbox's label. If you need to provide HTML in the label, use the `label` slot instead.	`string`
`name`	The name of the checkbox. This will be submitted with the form as a name/value pair.	`string`
`value`	The checkbox's value.	`string`	`''`
`checked`	The checkbox's checked state.	`boolean`	`false`
`indeterminate`	Puts the checkbox in an indeterminate state.	`boolean`	`false`
`disabled`	Disables the checkbox.	`boolean`	`false`
`appearance`	The type of checkbox to render.	`'normal' 'filled'`	`'normal'`
`size`	The checkbox's size.	`'xs' 'sm' 'md' 'lg' 'xl'`	`'md'`
`form`	The form to associate this control with. If omitted, the closest containing `<form>` will be used. The value of this attribute must be an ID of a form in the same document or shadow root.	`string`
`required`	Makes the checkbox required. Form submission will not be allowed until the checkbox is checked.	`boolean`	`false`
`customValidity` `custom-validity`	You can provide a custom error message to force the checkbox to be invalid. To clear the error, set this to an empty string.	`string`	`''`

Methods Jump to heading

Checkbox supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods

Name	Description	Arguments
`focus()`	Sets focus to the checkbox.
`blur()`	Removes focus from the checkbox.
`checkValidity()`	Checks if the form control has any restraints and whether it satisfies them. If invalid, `false` will be returned and the `invalid` event will be dispatched. If valid, `true` will be returned.
`reportValidity()`	Checks if the form control has any restraints and whether it satisfies them. If invalid, `false` will be returned and the `invalid` event will be dispatched. In addition, the problem will be reported to the user. If valid, `true` will be returned.

Events Jump to heading

Checkbox dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name	Description
`quiet-blur`	Emitted when the checkbox loses focus. This event does not bubble.
`quiet-change`	Emitted when the user commits changes to the checkbox's value.
`quiet-focus`	Emitted when the checkbox receives focus. This event does not bubble.
`quiet-input`	Emitted when the checkbox receives input.

CSS parts Jump to heading

Checkbox exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name	Description	CSS selector
`label`	The `<label>` that wraps the entire control.	`::part(label)`
`visual-box`	The element that wraps the internal checkbox.	`::part(visual-box)`
`check-icon`	The check icon, a `<quiet-icon>` element.	`::part(check-icon)`
`check-icon__svg`	The check icon's `svg` part.	`::part(check-icon__svg)`
`indeterminate-icon`	The indeterminate icon, a `<quiet-icon>` element.	`::part(indeterminate-icon)`
`indeterminate-icon__svg`	The indeterminate icon's `<svg>` part.	`::part(indeterminate-icon__svg)`

Custom States Jump to heading

Checkbox has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name	Description	CSS selector
`checked`	Applied when the checkbox is checked.	`:state(checked)`
`disabled`	Applied when the checkbox is disabled.	`:state(disabled)`
`focused`	Applied when the checkbox has focus.	`:state(focused)`
`user-valid`	Applied when the checkbox is valid and the user has sufficiently interacted with it.	`:state(user-valid)`
`user-invalid`	Applied when the checkbox is invalid and the user has sufficiently interacted with it.	`:state(user-invalid)`

Dependencies Jump to heading

Checkbox automatically imports the following elements. Sub-dependencies are also included in this list.

<quiet-icon>

Checkbox

Examples Jump to heading #

Checked initially Jump to heading #

Filled checkboxes Jump to heading #

Changing the size Jump to heading #

Indeterminate Jump to heading #

Disabling Jump to heading #

Validation Jump to heading #

Using custom validation Jump to heading #

Styling validation Jump to heading #

Styling checkboxes Jump to heading #

API Jump to heading #

Importing Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

Methods Jump to heading #

Events Jump to heading #

CSS parts Jump to heading #

Custom States Jump to heading #

Dependencies Jump to heading #