Skip to content

Checkbox

<quiet-checkbox> stable since 1.0

Allows users to 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

Labels and descriptions Jump to heading

The checkbox's label is provided via its default slot. You can use the description attribute to provide a plain text description. If you want to provide HTML, use the description slot instead.

I agree to the terms and conditions By checking this box, you agree to our catnip usage policy 
<quiet-checkbox name="terms" value="accepted">
  I agree to the terms and conditions
  <span slot="description">
    By checking this box, you agree to our <a href="#">catnip usage policy</a>
  </span>
</quiet-checkbox>

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 setCustomValidity() method 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" id="checkbox__custom-validation">
  <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>

<script type="module">
  import { allDefined } from '/dist/quiet.js';

  await allDefined();

  const form = document.getElementById('checkbox__custom-validation');
  const checkbox = form.querySelector('quiet-checkbox');

  checkbox.setCustomValidity('Not so fast, bubba!');
</script>

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-md);
    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 Self-hosted

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

import 'https://cdn.quietui.org/v2.0.0/components/checkbox/checkbox.js';

To manually import <quiet-checkbox> from a self-hosted distribution, use the following code. Remember to replace /path/to/quiet with the appropriate local path. 

import '/path/to/quiet/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.
description The checkbox's description. For plain-text descriptions, you can use the description 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 Reflects Type Default
label The checkbox's label. If you need to provide HTML in the label, use the label slot instead. string
description The checkbox's description. If you need to provide HTML in the description, use the description 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

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.
setCustomValidity() Sets a custom validation message for the form control. If this message is not an empty string, then the form control is considered invalid and the specified message will be displayed to the user when reporting validity. Setting an empty string clears the custom validity state. message: string

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)
description The element that contains the checkbox's description. ::part(description)
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.

Search this website Toggle dark mode View the code on GitHub Follow @quietui.org on Bluesky Follow @quiet_ui on X

    No results found