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.

HTML
<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.

HTML
<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.

HTML
<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.

HTML
<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.

HTML
<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.

Choose all that apply
HTML
<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 for attribute to a unique input id. 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 name and an explicit value when that choice is submitted. Only checked, enabled checkboxes contribute entries to native form submission; unchecked options are omitted.
  • Use fieldset and legend to name a related group. Checkbox options remain independent and allow multiple selections.
  • Connect hints and errors with aria-describedby. .is-invalid styles an error and aria-invalid communicates it; neither performs validation. Use native required for an individual mandatory checkbox. Requiring at least one selection from a group needs application validation; see Form.
  • Set mixed state through input.indeterminate in your application and update it when child selections change. The browser exposes that state through the native checkbox; keep checked consistent 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.

TokenDefaultPurposeScope / state
--form-check-gapvar(--spacer-2)Space between the input and label..form-check
--form-check-input-size1remCheckbox or radio width and height..form-check-input
--form-check-input-border-radiusvar(--border-radius-sm, 0.25rem)Checkbox corner radius; radios remain circular..form-check-input
--form-check-input-bg-colorvar(--bg-surface)Unchecked control background..form-check-input
--form-check-input-border-widthvar(--border-width)Control border thickness..form-check-input
--form-check-input-border-colorvar(--control-border-color)Unchecked control border..form-check-input
--form-check-input-checked-bg-colorvar(--primary)Checked or indeterminate background..form-check-input (checked / indeterminate)
--form-check-input-checked-border-colorvar(--primary)Checked or indeterminate border..form-check-input (checked / indeterminate)
--form-check-input-checked-colorvar(--on-primary)Checkmark, indeterminate bar or radio dot color..form-check-input (checked / indeterminate)
--form-check-disabled-bg-colorvar(--disabled-bg-color)Background color while disabled..form-check-input (disabled)
--form-check-disabled-border-colorvar(--disabled-border-color)Border color while disabled..form-check-input (disabled)
--form-check-transition-durationvar(--transition-duration)Duration of visual state transitions..form-check
--form-check-transition-easingvar(--transition-easing)Timing curve for visual state transitions..form-check