Checkbox
Native checkboxes with checked, mixed, focus and validation states.
When to use
Use a checkbox for an independent yes-or-no choice, or a group where several options can be selected. Use Radio when exactly one option can be selected from a group, and Switch for an on-or-off setting with an immediate effect.
Default
Combine .form-check with a native checkbox using .form-check-input. Keep its visible label connected through matching for and id attributes.
<div class="form-check">
<input class="form-check-input" id="checkboxDefault" name="checkboxDefault" type="checkbox" />
<label class="form-label" for="checkboxDefault">Default checkbox</label>
</div>Checked
Use the native checked attribute for the initial selection. The current checked property determines whether the checkbox is selected when a form is submitted.
<div class="form-check">
<input
class="form-check-input"
id="checkboxChecked"
name="checkboxChecked"
type="checkbox"
checked />
<label class="form-label" for="checkboxChecked">Checked checkbox</label>
</div>Indeterminate
Set the native indeterminate JavaScript property for a mixed state, such as a parent option whose children are only partly selected. It does not change checked or the submitted value. Update both properties when synchronizing a parent checkbox with its children.
<div class="form-check">
<input
class="form-check-input"
id="checkboxIndeterminate"
name="checkboxIndeterminate"
type="checkbox" />
<label class="form-label" for="checkboxIndeterminate">Mixed checkbox</label>
</div>
<script>
const checkbox = document.querySelector('#checkboxIndeterminate');
checkbox.indeterminate = true;
</script>Invalid
Combine .is-invalid and aria-invalid="true". Link adjacent feedback with aria-describedby and its id.
Please accept this option.
<div>
<div class="form-check">
<input
class="form-check-input is-invalid"
id="checkboxInvalid"
name="checkboxInvalid"
type="checkbox"
aria-invalid="true"
aria-describedby="checkboxInvalidFeedback" />
<label class="form-label" for="checkboxInvalid">Invalid checkbox</label>
</div>
<div class="invalid-feedback" id="checkboxInvalidFeedback">Please accept this option.</div>
</div>Disabled
Use the native disabled attribute when an option is unavailable. Disabled checkboxes are skipped in keyboard navigation and omitted from native form submission.
<div class="form-check">
<input
class="form-check-input"
id="checkboxDisabled"
name="checkboxDisabled"
type="checkbox"
disabled />
<label class="form-label" for="checkboxDisabled"><span>Disabled checkbox</span></label>
</div>Checkbox group
Group related checkboxes with fieldset and a visible legend. Give each option a distinct value; selected options with the same name submit repeated entries under that name.
<fieldset class="border border-0 min-w-0">
<legend class="mb-2">Choose all that apply</legend>
<div class="d-flex flex-column gap-2">
<div class="form-check">
<input
class="form-check-input"
id="checkboxGroupOne"
name="checkboxGroup"
type="checkbox"
value="option-one" />
<label class="form-label" for="checkboxGroupOne">Option one</label>
</div>
<div class="form-check">
<input
class="form-check-input"
id="checkboxGroupTwo"
name="checkboxGroup"
type="checkbox"
value="option-two"
checked />
<label class="form-label" for="checkboxGroupTwo">Option two</label>
</div>
<div class="form-check">
<input
class="form-check-input"
id="checkboxGroupThree"
name="checkboxGroup"
type="checkbox"
value="option-three" />
<label class="form-label" for="checkboxGroupThree">Option three</label>
</div>
</div>
</fieldset>Accessibility and behavior
- Match each visible label’s
forattribute to a unique inputid. Clicking the label toggles its checkbox and increases the usable target area. - Use Tab and Shift+Tab to move between enabled checkboxes, and Space to toggle the focused option. Preserve the native input and visible focus indicator.
- Give each checkbox a
nameand an explicitvaluewhen that choice is submitted. Only checked, enabled checkboxes contribute entries to native form submission; unchecked options are omitted. - Use
fieldsetandlegendto name a related group. Checkbox options remain independent and allow multiple selections. - Connect hints and errors with
aria-describedby..is-invalidstyles an error andaria-invalidcommunicates it; neither performs validation. Use nativerequiredfor an individual mandatory checkbox. Requiring at least one selection from a group needs application validation; see Form. - Set mixed state through
input.indeterminatein your application and update it when child selections change. The browser exposes that state through the native checkbox; keepcheckedconsistent with the intended submitted value.
CSS variables
Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.
| Token | Default | Purpose | Scope / state |
|---|---|---|---|
--form-check-gap | var(--spacer-2) | Space between the input and label. | .form-check |
--form-check-input-size | 1rem | Checkbox or radio width and height. | .form-check-input |
--form-check-input-border-radius | var(--border-radius-sm, 0.25rem) | Checkbox corner radius; radios remain circular. | .form-check-input |
--form-check-input-bg-color | var(--bg-surface) | Unchecked control background. | .form-check-input |
--form-check-input-border-width | var(--border-width) | Control border thickness. | .form-check-input |
--form-check-input-border-color | var(--control-border-color) | Unchecked control border. | .form-check-input |
--form-check-input-checked-bg-color | var(--primary) | Checked or indeterminate background. | .form-check-input (checked / indeterminate) |
--form-check-input-checked-border-color | var(--primary) | Checked or indeterminate border. | .form-check-input (checked / indeterminate) |
--form-check-input-checked-color | var(--on-primary) | Checkmark, indeterminate bar or radio dot color. | .form-check-input (checked / indeterminate) |
--form-check-disabled-bg-color | var(--disabled-bg-color) | Background color while disabled. | .form-check-input (disabled) |
--form-check-disabled-border-color | var(--disabled-border-color) | Border color while disabled. | .form-check-input (disabled) |
--form-check-transition-duration | var(--transition-duration) | Duration of visual state transitions. | .form-check |
--form-check-transition-easing | var(--transition-easing) | Timing curve for visual state transitions. | .form-check |