Components

Checkbox

A box people tick to opt in, or to pick any number of options from a set.

Import

import { Checkbox } from '@oztix/roadie-components/checkbox'
import { CheckboxGroup } from '@oztix/roadie-components/checkbox-group'

Examples

Default

A single checkbox for a yes or no choice. Pass label and the whole row becomes the click target.

<Checkbox label='Send me news about upcoming events' />

With description

<Checkbox
  label='Add ticket insurance'
  description='Get a refund if you cannot make it on the night.'
/>

Group

Use CheckboxGroup when people can pick more than one option. It tracks the ticked values as an array.

<CheckboxGroup defaultValue={['rock']}>
  <CheckboxGroup.Label>Genres</CheckboxGroup.Label>
  <CheckboxGroup.Item value='rock' label='Rock' />
  <CheckboxGroup.Item value='jazz' label='Jazz' />
  <CheckboxGroup.Item value='hip-hop' label='Hip hop' />
  <CheckboxGroup.Item value='electronic' label='Electronic' />
</CheckboxGroup>

Select all

Give the group allValues and add an item with parent. The parent ticks or clears every child, and shows a dash when only some are ticked. The group must be controlled.

function GenreFilter() {
  const genres = ['rock', 'jazz', 'hip-hop', 'electronic']
  const [value, setValue] = useState(['rock', 'jazz'])

  return (
    <CheckboxGroup value={value} onValueChange={setValue} allValues={genres}>
      <CheckboxGroup.Label>Filter by genre</CheckboxGroup.Label>
      <CheckboxGroup.Item parent label='All genres' />
      <div className='grid gap-2 ps-6'>
        <CheckboxGroup.Item value='rock' label='Rock' />
        <CheckboxGroup.Item value='jazz' label='Jazz' />
        <CheckboxGroup.Item value='hip-hop' label='Hip hop' />
        <CheckboxGroup.Item value='electronic' label='Electronic' />
      </div>
    </CheckboxGroup>
  )
}

render(<GenreFilter />)

With Field

Wrap a checkbox in Field to get helper and error text. The checkbox picks up invalid, required and disabled from the Field, and screen readers hear the helper or error text with it.

function TermsOptIn() {
  const [agreed, setAgreed] = useState(false)
  const [submitted, setSubmitted] = useState(false)
  const invalid = submitted && !agreed

  return (
    <form
      noValidate
      className='grid justify-items-start gap-4'
      onSubmit={(event) => {
        event.preventDefault()
        setSubmitted(true)
      }}
    >
      <Field invalid={invalid} required>
        <Checkbox
          checked={agreed}
          onCheckedChange={setAgreed}
          label={
            <>
              I agree to the <Link href='#' className='underline'>terms and conditions</Link>
            </>
          }
        />
        <Field.ErrorText>Accept the terms to buy tickets.</Field.ErrorText>
      </Field>
      <Button type='submit' intent='accent' emphasis='strong'>
        Buy tickets
      </Button>
    </form>
  )
}

render(<TermsOptIn />)

A group in a Field takes its label from Field.Label.

<Field required>
  <Field.Label showIndicator>Where did you hear about Neon Lanes?</Field.Label>
  <CheckboxGroup>
    <CheckboxGroup.Item value='social' label='Social media' />
    <CheckboxGroup.Item value='radio' label='Radio' />
    <CheckboxGroup.Item value='friend' label='A friend' />
  </CheckboxGroup>
  <Field.HelperText>Tick all that apply.</Field.HelperText>
</Field>

Variants

Horizontal direction

<CheckboxGroup direction='horizontal'>
  <CheckboxGroup.Item value='fri' label='Friday' />
  <CheckboxGroup.Item value='sat' label='Saturday' />
  <CheckboxGroup.Item value='sun' label='Sunday' />
</CheckboxGroup>

Emphasis

normal turns each item into a card, with the box on the right. Set it on the group, or on a single Checkbox.

Normal

<CheckboxGroup emphasis='normal' defaultValue={['parking']}>
  <CheckboxGroup.Item
    value='parking'
    label='Parking pass'
    description='A spot in the Southbank car park.'
  />
  <CheckboxGroup.Item
    value='merch'
    label='Merch bundle'
    description='Tee and tote, collect at the door.'
  />
</CheckboxGroup>

States

<div className='grid gap-4'>
  <div className='grid gap-1'>
    <p className='text-sm text-subtle'>Unchecked</p>
    <Checkbox label='Send me event news' />
  </div>
  <div className='grid gap-1'>
    <p className='text-sm text-subtle'>Checked</p>
    <Checkbox label='Send me event news' defaultChecked />
  </div>
  <div className='grid gap-1'>
    <p className='text-sm text-subtle'>Indeterminate</p>
    <Checkbox label='All genres' indeterminate />
  </div>
  <div className='grid gap-1'>
    <p className='text-sm text-subtle'>Invalid</p>
    <Checkbox label='I agree to the terms and conditions' invalid />
  </div>
  <div className='grid gap-1'>
    <p className='text-sm text-subtle'>Disabled</p>
    <Checkbox label='Send me event news' disabled defaultChecked />
  </div>
</div>

Guidelines

Use a checkbox for choices that take effect on submit. For a setting that applies straight away, use a switch.
Use a RadioGroup when people must pick exactly one option.
Word the label so ticking it means yes. "Send me event news", not "Don't send me event news".
Never tick a marketing or terms opt-in for people by default.

Accessibility

Keyboard: Tab moves between checkboxes. Space ticks or clears the focused one.
ARIA: Base UI renders role="checkbox" with aria-checked, which reads mixed when indeterminate. CheckboxGroup renders role="group".
Labels: label wraps the box in a <label>, so it names the checkbox and the whole row is clickable. Label a group with CheckboxGroup.Label, Field.Label, or a Fieldset legend.

API reference

Checkbox

Base UI

idstring: The id of the input element.
namestring: Identifies the field when a form is submitted.
Defaults to undefined.
formstring: Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.
checkedboolean: Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the `defaultChecked` prop instead.
Defaults to undefined.
defaultCheckedboolean: Whether the checkbox is initially ticked. To render a controlled checkbox, use the `checked` prop instead.
Defaults to false.
disabledboolean: Whether the component should ignore user interaction.
Defaults to false.
onCheckedChange((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element; }) => void): Event handler called when the checkbox is ticked or unticked.
readOnlyboolean: Whether the user should be unable to tick or untick the checkbox.
Defaults to false.
requiredboolean: Whether the user must tick the checkbox before submitting a form.
Defaults to false.
indeterminateboolean: Whether the checkbox is in a mixed state: neither ticked, nor unticked.
Defaults to false.
inputRefRef<HTMLInputElement>: A ref to access the hidden `<input>` element.
parentboolean: Whether the checkbox controls a group of child checkboxes. Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group).
Defaults to false.
uncheckedValuestring: The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.
valuestring: The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted. When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on".
classNamestring | ((state: CheckboxRootState) => string): CSS class applied to the element, or a function that returns a class based on the component's state.
labelReactNode
descriptionReactNode
emphasis"subtler" | "normal": Ignored inside a `CheckboxGroup`, which sets it for every item.
invalidboolean

Inherited from NonNativeButtonProps

nativeButtonboolean: Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
Defaults to false.

API reference

CheckboxGroup

Base UI

valuestring[]: Names of the checkboxes in the group that should be ticked. To render an uncontrolled checkbox group, use the `defaultValue` prop instead.
defaultValuestring[]: Names of the checkboxes in the group that should be initially ticked. To render a controlled checkbox group, use the `value` prop instead.
onValueChange((value: string[], eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element; }) => void): Event handler called when a checkbox in the group is ticked or unticked. Provides the new value as an argument.
allValuesstring[]: Names of all checkboxes in the group. Use this when creating a parent checkbox.
disabledboolean: Whether the component should ignore user interaction.
Defaults to false.
classNamestring | ((state: CheckboxGroupState) => string): CSS class applied to the element, or a function that returns a class based on the component's state.
direction"horizontal" | "vertical"
emphasis"subtler" | "normal"
invalidboolean
requiredboolean

CheckboxGroup.ErrorText

No additional props. It forwards all standard HTML attributes to the underlying element.

CheckboxGroup.HelperText

No additional props. It forwards all standard HTML attributes to the underlying element.

CheckboxGroup.Item

labelReactNode
classNamestring | ((state: CheckboxRootState) => string): CSS class applied to the element, or a function that returns a class based on the component's state.
descriptionReactNode
invalidboolean

Inherited from CheckboxRootProps

formstring: Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.
defaultCheckedboolean: Whether the checkbox is initially ticked. To render a controlled checkbox, use the `checked` prop instead.
Defaults to false.
idstring: The id of the input element.
valuestring: The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted. When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on".
namestring: Identifies the field when a form is submitted.
Defaults to undefined.
checkedboolean: Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the `defaultChecked` prop instead.
Defaults to undefined.
disabledboolean: Whether the component should ignore user interaction.
Defaults to false.
onCheckedChange((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element; }) => void): Event handler called when the checkbox is ticked or unticked.
readOnlyboolean: Whether the user should be unable to tick or untick the checkbox.
Defaults to false.
requiredboolean: Whether the user must tick the checkbox before submitting a form.
Defaults to false.
indeterminateboolean: Whether the checkbox is in a mixed state: neither ticked, nor unticked.
Defaults to false.
inputRefRef<HTMLInputElement>: A ref to access the hidden `<input>` element.
parentboolean: Whether the checkbox controls a group of child checkboxes. Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group).
Defaults to false.
uncheckedValuestring: The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.

Inherited from NonNativeButtonProps

nativeButtonboolean: Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
Defaults to false.

CheckboxGroup.Label

showIndicatorboolean

Previous page← Autocomplete Next pageCombobox →