Skip to main content
USWDS + Tailwind

Checkbox

Use checkboxes when people can select one or more options. Compare standard and tiled checkbox styles.

Examples

Default

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
Select any historical figure
checkbox-demo.tsx
import { Checkbox, Fieldset } from '@uswds-tailwind/react'


export default function CheckboxDemo() {
  return (
    <Fieldset.Root className="max-w-xs">
      <Fieldset.Legend>Select any historical figure</Fieldset.Legend>
      <Checkbox.Group>
        <Checkbox.Root>
          <Checkbox.Input value="sojourner-truth" />
          <Checkbox.Control />
          <Checkbox.Label>Sojourner Truth</Checkbox.Label>
        </Checkbox.Root>
        <Checkbox.Root>
          <Checkbox.Input value="frederick-douglass" />
          <Checkbox.Control />
          <Checkbox.Label>Frederick Douglass</Checkbox.Label>
        </Checkbox.Root>
        <Checkbox.Root>
          <Checkbox.Input value="booker-t-washington" />
          <Checkbox.Control />
          <Checkbox.Label>Booker T. Washington</Checkbox.Label>
        </Checkbox.Root>
        <Checkbox.Root>
          <Checkbox.Input value="george-washington-carver" disabled />
          <Checkbox.Control />
          <Checkbox.Label>George Washington Carver</Checkbox.Label>
        </Checkbox.Root>
      </Checkbox.Group>
    </Fieldset.Root>
  )
}

Tiled

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
Select any historical figure
checkbox-tiled-demo.tsx
import { Checkbox, Fieldset } from '@uswds-tailwind/react'


export default function CheckboxTiledDemo() {
  return (
    <Fieldset.Root className="max-w-xs">
      <Fieldset.Legend>Select any historical figure</Fieldset.Legend>
      <Checkbox.Group>
        <Checkbox.Root tile>
          <Checkbox.Input value="sojourner-truth" />
          <Checkbox.Control />
          <Checkbox.Label>
            Sojourner Truth
            <Checkbox.Description>
              This is optional text that can describe the choice in more detail.
            </Checkbox.Description>
          </Checkbox.Label>
        </Checkbox.Root>
        <Checkbox.Root tile>
          <Checkbox.Input value="frederick-douglass" />
          <Checkbox.Control />
          <Checkbox.Label>Frederick Douglass</Checkbox.Label>
        </Checkbox.Root>
        <Checkbox.Root tile>
          <Checkbox.Input value="booker-t-washington" />
          <Checkbox.Control />
          <Checkbox.Label>Booker T. Washington</Checkbox.Label>
        </Checkbox.Root>
        <Checkbox.Root tile>
          <Checkbox.Input value="george-washington-carver" disabled />
          <Checkbox.Control />
          <Checkbox.Label>George Washington Carver</Checkbox.Label>
        </Checkbox.Root>
      </Checkbox.Group>
    </Fieldset.Root>
  )
}

Component API

Put Input, Control, Label, and optional Description inside Root. Group coordinates multiple checkboxes by value.

Group<div>

Collects selected item values.

PropTypeDefaultDescription
defaultValuestring[][]Initial values used to accumulate onValueChange results. Set defaultChecked on each Input to match these values.
onValueChange(values: string[]) => void—Receives the selected values.

Root<label>

Connects Input, Control, Label, and optional Description.

PropTypeDescription
valuestringValue used when Root is inside Group.
onCheckedChange({ checked: boolean }) => voidReceives checked-state changes.
tilebooleanUses the tiled visual treatment.

Input<input>

Native checkbox control; pass native disabled and required props here.

AttributeValuePurpose
data-disabledPresent when disabledStyle the disabled state.
data-invalidPresent when invalidStyle the error state.

Control<div>

Shows a check mark when Input is checked.

Label<div>

Put the checkbox text beside Control.

Description<div>

Add optional help text for this choice.