Checkbox

Checkboxes are used to select one or several options in a list.

Examples

Base

Web Component
HTML Blueprint

<div class="chi-form__item">
  <chi-checkbox id="example__base" label="Checkbox"></chi-checkbox>
</div>

<div class="chi-form__item">
  <div class="chi-checkbox">
    <input type="checkbox" class="chi-checkbox__input" id="example__base">
    <label class="chi-checkbox__label" for="example__base">Checkbox</label>
  </div>
</div>

Checked

Use the checked boolean attribute to set the default value of a checkbox to true.

Web Component
HTML Blueprint

<div class="chi-form__item">
  <chi-checkbox id="example__checked" label="Checkbox" checked></chi-checkbox>
</div>

<div class="chi-form__item">
  <div class="chi-checkbox">
    <input type="checkbox" class="chi-checkbox__input" id="example__checked" checked>
    <label class="chi-checkbox__label" for="example__checked">Checkbox</label>
  </div>
</div>

Indeterminate

A checkbox cannot be set to indeterminate state by an HTML attribute - it must be set by JavaScript. Use the class -indeterminate to achieve the corresponding style of the checkbox.

Web Component
HTML Blueprint

<div class="chi-form__item">
  <chi-checkbox id="example__indeterminate" label="Checkbox" indeterminate></chi-checkbox>
</div>

<div class="chi-form__item">
  <div class="chi-checkbox">
    <input type="checkbox" class="chi-checkbox__input -indeterminate" id="example__indeterminate">
    <label class="chi-checkbox__label" for="example__indeterminate">Checkbox</label>
  </div>
</div>

<!-- JavaScript -->
<script>
  var checkbox = document.getElementById('example__indeterminate');
  
  checkbox.indeterminate = true;
</script>

Disabled

Use the disabled boolean attribute to prevent users from interacting with an input. Disabled inputs are not submitted with the form and can not receive any browsing events such as mouse clicks or focus. Note: The required attribute can not be used on inputs with a disabled attribute specified.

Web Component
HTML Blueprint

<div class="chi-form__item">
  <chi-checkbox id="example__disabled" label="Checkbox" disabled></chi-checkbox>
</div>

<div class="chi-form__item">
  <div class="chi-checkbox">
    <input type="checkbox" class="chi-checkbox__input" id="example__disabled" disabled>
    <label class="chi-checkbox__label" for="example__disabled">Checkbox</label>
  </div>
</div>

Required

Use the required boolean attribute to indicate which checkboxes must be completed before submitting a form. This is useful for ensuring users accept a Terms of Service, Privacy Policy, or other legal requirement.

Web Component
HTML Blueprint

<div class="chi-form__item">
  <chi-checkbox id="example__required" label="I accept the Terms of Service" required></chi-checkbox>
</div>

<div class="chi-form__item">
  <div class="chi-checkbox">
    <input type="checkbox" class="chi-checkbox__input" id="example__required" required>
    <label class="chi-checkbox__label" for="example__required">
      I accept the Terms of Service
      <abbr class="chi-label__required" aria-label="Required field">*</abbr>
    </label>
  </div>
</div>

Help

Use chi-label__help to include a help icon that displays helpful information about an input in a popover. A help icon must be contained within an icon button to ensure it receives focus when a user tabs through a form.

Web Component
HTML Blueprint

<div class="chi-form__item">
  <chi-checkbox id="example__help" label="Checkbox">
    <div class="chi-label__help" slot="chi-checkbox__help">
      <chi-button id="example__help_button" type="icon" size="xs" variant="flat" alternative-text="Help">
        <chi-icon icon="circle-info-outline"></chi-icon>
      </chi-button>
    </div>
  </chi-checkbox>
</div>
<chi-popover id="example__help_popover" position="top" variant="text" arrow="arrow" reference="#example__help_button">
  Helpful information goes here.
</chi-popover>

<script>
  document.querySelector("#example__help_button")
    .addEventListener("click", function() {
      var popoverElem = document.querySelector("#example__help_popover");
      popoverElem.toggle();
    });
</script>

This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.

<div class="chi-form__item">
  <div class="chi-checkbox">
    <input class="chi-checkbox__input" type="checkbox" id="example__help">
    <label class="chi-checkbox__label" for="example__help">Checkbox</label>
    <div class="chi-label__help">
      <button class="chi-button -icon -xs -flat" id="example__help_button" aria-label="Help" data-target="#example__help_popover">
        <i class="chi-icon icon-circle-info-outline" aria-hidden="true"></i>
      </button>
      <section class="chi-popover chi-popover--top -animated" id="example__help_popover" aria-modal="true" role="dialog" aria-hidden="true" x-placement="top">
        <div class="chi-popover__content">
          <p class="chi-popover__text">Helpful information goes here.</p>
        </div>
      </section>
    </div>
  </div>
</div>

<script>chi.popover(document.getElementById('example__help_button'));</script>

Message

Add a message below a checkbox to store descriptions, validation feedback, and other helpful information.

Optional helper message

Web Component
HTML Blueprint

<div class="chi-form__item">
  <chi-checkbox id="example__message" label="Checkbox"></chi-checkbox>
  <div class="chi-label -status">Optional helper message</div>
</div>

<div class="chi-form__item">
  <div class="chi-checkbox">
    <input type="checkbox" class="chi-checkbox__input" id="example__message">
    <label class="chi-checkbox__label" for="example__message">Checkbox</label>
  </div>
  <div class="chi-label -status">Optional helper message</div>
</div>

Error

Use the -danger state to provide feedback to users when an input fails to validate. To meet accessibility requirements, danger inputs must include an error message explaining the failure and/or how to correct it.

Please accept the terms of service

Web Component
HTML Blueprint

<div class="chi-form__item">
  <chi-checkbox id="example__error" state="danger" label="I accept the Terms of Service" required></chi-checkbox>
  <div class="chi-label -status -danger">
    <chi-icon icon="circle-warning"></chi-icon>
    Please accept the terms of service
  </div>
</div>

<div class="chi-form__item">
  <div class="chi-checkbox">
    <input type="checkbox" class="chi-checkbox__input" id="example__error">
    <label class="chi-checkbox__label -danger" for="example__error">
      I accept the Terms of Service
      <abbr class="chi-label__required" aria-label="Required field">*</abbr>
    </label>
  </div>
  <div class="chi-label -status -danger">
    <i class="chi-icon icon-circle-warning" aria-hidden="true"></i>
    Please accept the terms of service
  </div>
</div>

Layout Variations

Stacked

Group checkboxes in chi-form__item for easy stacking.

Select options

Web Component
HTML Blueprint

<fieldset>
  <legend class="chi-label">Select options</legend>
  <div class="chi-form__item -mb--1">
    <chi-checkbox id="example__stacked1" label="Option 1"></chi-checkbox>
  </div>
  <div class="chi-form__item">
    <chi-checkbox id="example__stacked2" label="Option 2"></chi-checkbox>
  </div>
</fieldset>

<fieldset>
  <legend class="chi-label">Select options</legend>
  <div class="chi-form__item -mb--1">
    <div class="chi-checkbox">
      <input type="checkbox" class="chi-checkbox__input" id="example__stacked1">
      <label class="chi-checkbox__label" for="example__stacked1">Option 1</label>
    </div>
  </div>
  <div class="chi-form__item">
    <div class="chi-checkbox">
      <input type="checkbox" class="chi-checkbox__input" id="example__stacked2">
      <label class="chi-checkbox__label" for="example__stacked2">Option 2</label>
    </div>
  </div>
</fieldset>

Grid

Use chi-grid to render a group of checkboxes in a responsive grid. In the example below, the checkboxes display in 4 columns on medium screens and up, 2 columns on small screens, and 1 column on x-small screens.

Select options

Web Component
HTML Blueprint

<fieldset>
  <div class="chi-grid">
    <div class="chi-col -w--12 -mb--1">
      <legend class="chi-label">Select options</legend>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <chi-checkbox id="example__grid1" label="Option 1"></chi-checkbox>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <chi-checkbox id="example__grid2" label="Option 2"></chi-checkbox>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <chi-checkbox id="example__grid3" label="Option 3"></chi-checkbox>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <chi-checkbox id="example__grid4" label="Option 4"></chi-checkbox>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <chi-checkbox id="example__grid5" label="Option 5"></chi-checkbox>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <chi-checkbox id="example__grid6" label="Option 6"></chi-checkbox>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <chi-checkbox id="example__grid7" label="Option 7"></chi-checkbox>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <chi-checkbox id="example__grid8" label="Option 8"></chi-checkbox>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <chi-checkbox id="example__grid9" label="Option 9"></chi-checkbox>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <chi-checkbox id="example__grid10" label="Option 10"></chi-checkbox>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <chi-checkbox id="example__grid11" label="Option 11"></chi-checkbox>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <chi-checkbox id="example__grid12" label="Option 12"></chi-checkbox>
      </div>
    </div>
  </div>
</fieldset>

<fieldset>
  <div class="chi-grid">
    <div class="chi-col -w--12 -mb--1">
      <legend class="chi-label">Select options</legend>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <div class="chi-checkbox">
          <input class="chi-checkbox__input" type="checkbox" id="example__grid1">
          <label class="chi-checkbox__label" for="example__grid1">Option 1</label>
        </div>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <div class="chi-checkbox">
          <input class="chi-checkbox__input" type="checkbox" id="example__grid2">
          <label class="chi-checkbox__label" for="example__grid2">Option 2</label>
        </div>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <div class="chi-checkbox">
          <input class="chi-checkbox__input" type="checkbox" id="example__grid3">
          <label class="chi-checkbox__label" for="example__grid3">Option 3</label>
        </div>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <div class="chi-checkbox">
          <input class="chi-checkbox__input" type="checkbox" id="example__grid4">
          <label class="chi-checkbox__label" for="example__grid4">Option 4</label>
        </div>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <div class="chi-checkbox">
          <input class="chi-checkbox__input" type="checkbox" id="example__grid5">
          <label class="chi-checkbox__label" for="example__grid5">Option 5</label>
        </div>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <div class="chi-checkbox">
          <input class="chi-checkbox__input" type="checkbox" id="example__grid6">
          <label class="chi-checkbox__label" for="example__grid6">Option 6</label>
        </div>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <div class="chi-checkbox">
          <input class="chi-checkbox__input" type="checkbox" id="example__grid7">
          <label class="chi-checkbox__label" for="example__grid7">Option 7</label>
        </div>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <div class="chi-checkbox">
          <input class="chi-checkbox__input" type="checkbox" id="example__grid8">
          <label class="chi-checkbox__label" for="example__grid8">Option 8</label>
        </div>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <div class="chi-checkbox">
          <input class="chi-checkbox__input" type="checkbox" id="example__grid9">
          <label class="chi-checkbox__label" for="example__grid9">Option 9</label>
        </div>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <div class="chi-checkbox">
          <input class="chi-checkbox__input" type="checkbox" id="example__grid10">
          <label class="chi-checkbox__label" for="example__grid10">Option 10</label>
        </div>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <div class="chi-checkbox">
          <input class="chi-checkbox__input" type="checkbox" id="example__grid11">
          <label class="chi-checkbox__label" for="example__grid11">Option 11</label>
        </div>
      </div>
    </div>
    <div class="chi-col -w--12 -w-md--3 -w-sm--6 -mb--1">
      <div class="chi-form__item">
        <div class="chi-checkbox">
          <input class="chi-checkbox__input" type="checkbox" id="example__grid12">
          <label class="chi-checkbox__label" for="example__grid12">Option 12</label>
        </div>
      </div>
    </div>
  </div>
</fieldset>

Inline

Apply the class -inline to chi-form__item to display two or more checkboxes in one row.

Select options

Web Component
HTML Blueprint

<fieldset>
  <legend class="chi-label">Select options</legend>
  <div class="chi-form__item -inline">
    <chi-checkbox id="example__inline1" label="Option 1"></chi-checkbox>
  </div>
  <div class="chi-form__item -inline">
    <chi-checkbox id="example__inline2" label="Option 2"></chi-checkbox>
  </div>
</fieldset>

<fieldset>
  <legend class="chi-label">Select options</legend>
  <div class="chi-form__item -inline">
    <div class="chi-checkbox">
      <input type="checkbox" class="chi-checkbox__input" id="example__inline1">
      <label class="chi-checkbox__label" for="example__inline1">Option 1</label>
    </div>
  </div>
  <div class="chi-form__item -inline">
    <div class="chi-checkbox">
      <input type="checkbox" class="chi-checkbox__input" id="example__inline2">
      <label class="chi-checkbox__label" for="example__inline2">Option 2</label>
    </div>
  </div>
</fieldset>

Checkbox List

Checkbox lists are used to wrap a series of checkboxes in a list. To render a series of checkboxes in a list, apply the class -list to chi-form__item.

Web Component
HTML Blueprint

<fieldset>
  <legend class="chi-label">Select options</legend>
  <ul class="chi-form__item -list">
    <li class="chi-form__item">
      <chi-checkbox id="example__list1" label="Option 1"></chi-checkbox>
    </li>
    <li class="chi-form__item">
      <chi-checkbox id="example__list2" label="Option 2"></chi-checkbox>
    </li>
    <li class="chi-form__item">
      <chi-checkbox id="example__list3" label="Option 3"></chi-checkbox>
    </li>
    <li class="chi-form__item">
      <chi-checkbox id="example__list4" label="Option 4"></chi-checkbox>
    </li>
    <li class="chi-form__item">
      <chi-checkbox id="example__list5" label="Option 5"></chi-checkbox>
    </li>
  </ul>
</fieldset>

<fieldset>
  <legend class="chi-label">Select options</legend>
  <ul class="chi-form__item -list">
    <li class="chi-form__item">
      <div class="chi-checkbox">
        <input type="checkbox" class="chi-checkbox__input" id="example__list1">
        <label class="chi-checkbox__label" for="example__list1">Option 1</label>
      </div>
    </li>
    <li class="chi-form__item">
      <div class="chi-checkbox">
        <input type="checkbox" class="chi-checkbox__input" id="example__list2">
        <label class="chi-checkbox__label" for="example__list2">Option 2</label>
      </div>
    </li>
    <li class="chi-form__item">
      <div class="chi-checkbox">
        <input type="checkbox" class="chi-checkbox__input" id="example__list3">
        <label class="chi-checkbox__label" for="example__list3">Option 3</label>
      </div>
    </li>
    <li class="chi-form__item">
      <div class="chi-checkbox">
        <input type="checkbox" class="chi-checkbox__input" id="example__list4">
        <label class="chi-checkbox__label" for="example__list4">Option 4</label>
      </div>
    </li>
    <li class="chi-form__item">
      <div class="chi-checkbox">
        <input type="checkbox" class="chi-checkbox__input" id="example__list5">
        <label class="chi-checkbox__label" for="example__list5">Option 5</label>
      </div>
    </li>
  </ul>
</fieldset>

Web Component

Properties

Property	Attribute	Description	Type	Default
`checked`	`checked`	To render the checkbox in checked state	`boolean`	undefined
`disabled`	`disabled`	To disable the checkbox	`boolean`	undefined
`indeterminate`	`indeterminate`	To add indeterminate state to checkbox	`boolean`	undefined
`label`	`label`	To provide checkbox label as a string	`string`	undefined
`name`	`name`	To render the checkbox input with a respective name attribute	`string`	undefined
`required`	`required`	To indicate which form field is required	`boolean`	`false`
`state`	`state`	To indicate the state	`"danger" \| "success" \| "warning"`	undefined

Events

Event	Description	Type
`chiChange`	Triggered when the user selects or deselects the checkbox	`CustomEvent<boolean \| string>`

Accessibility

Keyboard Navigation

Key	Function
`Tab`	Moves focus to the next focusable element
`Shift + Tab`	Moves focus to the previous focusable element
`Space`	Toggles checkbox between checked and unchecked states

For comprehensive details on keyboard support for input fields, refer to our Keyboard Control Guide.

Visit WebAIM for keyboard techniques.

Use clear and descriptive labels for checkboxes to help users understand their purpose.
Ensure each checkbox has an associated label element using the for attribute to match the id attribute of the checkbox.
Assign unique id attributes to each checkbox to maintain accessibility and prevent conflicts.
The fieldset surrounds the entire grouping of checkboxes or radio buttons. The legend provides a description for the grouping.
Use the aria-describedby attribute to associate error messages with checkboxes for accessibility.
Ensure that error messages are tagged with unique id attributes and referenced correctly with aria-describedby on corresponding checkboxes.

Find live examples in the A11y style guide.

Roles and attributes

WAI-ARIA provides a grouping role that functions similarly to fieldset and legend.

Role	Element	Usage
`group`	`div`	Identifies the `div` element as a group container for the checkboxes.

Resources

W3 Checkbox Example: Information about the accordion accessible behavior.
A11y Style Guide: Gives core recommendations for the accessible checkboxes.
W3C Forms Tutorial: Provides guidance on creating accessible forms.
DigitalA11y Project: Find examples of accessible checkboxes.

Other recommendations

Explore additional accessibility tips in the general Accessibility Guide.

WCAG 2.2 Guidelines

Non-text Content: All non-text content that is presented to the user has a text alternative that serves the equivalent purpose. (Level A)
Info and Relationships: Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. (Level A)
Headings and Labels: Headings and labels describe topic or purpose. (Level AA)
Labels or Instructions: Labels or instructions are provided when content requires user input. (Level A)
Name, Role, Value: For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies. (Level A)