Antares
Components

Checkbox

Accessible checkbox component for multi-select options with support for indeterminate states, validation, keyboard navigation, and flexible group layouts.

Installation

npm install --save @godaddy/antares

Props

NameTypeDefault
children?ReactNode—

The content of the checkbox label.

className?string | undefined'react-aria-Checkbox'

Additional class names to apply to the checkbox component.

inputRef?RefObject<HTMLInputElement | null> | undefined—

A ref for the HTML input element.

isIndeterminate?boolean | undefined—

Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction.

value?string | undefined—

The value of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefvalue).

defaultSelected?boolean | undefined—

Whether the element should be selected (uncontrolled).

isSelected?boolean | undefined—

Whether the element should be selected (controlled).

onChange?((isSelected: boolean) => void) | undefined—

Handler that is called when the element's selection state changes.

isDisabled?boolean | undefined—

Whether the input is disabled.

isReadOnly?boolean | undefined—

Whether the input can be selected but not changed by the user.

isRequired?boolean | undefined—

Whether user input is required on the input before form submission.

isInvalid?boolean | undefined—

Whether the input value is invalid.

validate?((value: boolean) => ValidationError | true | null | undefined) | undefined—

A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.

autoFocus?boolean | undefined—

Whether the element should receive focus on render.

onFocus?((e: React.FocusEvent<Element, Element>) => void) | undefined—

Handler that is called when the element receives focus.

onBlur?((e: React.FocusEvent<Element, Element>) => void) | undefined—

Handler that is called when the element loses focus.

onFocusChange?((isFocused: boolean) => void) | undefined—

Handler that is called when the element's focus status changes.

onKeyDown?((e: KeyboardEvent) => void) | undefined—

Handler that is called when a key is pressed.

onKeyUp?((e: KeyboardEvent) => void) | undefined—

Handler that is called when a key is released.

name?string | undefined—

The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname).

form?string | undefined—

The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form).

excludeFromTabOrder?boolean | undefined—

Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.

id?string | undefined—

The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).

onPress?((e: PressEvent) => void) | undefined—

Handler that is called when the press is released over the target.

onPressStart?((e: PressEvent) => void) | undefined—

Handler that is called when a press interaction starts.

onPressEnd?((e: PressEvent) => void) | undefined—

Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.

onPressChange?((isPressed: boolean) => void) | undefined—

Handler that is called when the press state changes.

onPressUp?((e: PressEvent) => void) | undefined—

Handler that is called when a press is released over the target, regardless of whether it started on the target or not.

onClick?((e: React.MouseEvent<FocusableElement>) => void) | undefined—

**Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides additional event details for non-mouse interactions.

onHoverStart?((e: HoverEvent) => void) | undefined—

Handler that is called when a hover interaction starts.

onHoverEnd?((e: HoverEvent) => void) | undefined—

Handler that is called when a hover interaction ends.

onHoverChange?((isHovering: boolean) => void) | undefined—

Handler that is called when the hover state changes.

validationBehavior?"native" | "aria" | undefined'native'

Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.

style?StyleOrFunction<CheckboxRenderProps> | undefined—

The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state.

render?DOMRenderFunction<"label", CheckboxRenderProps> | undefined—

Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.

slot?string | null | undefined—

A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

Examples

Basic

A single checkbox with a label.

import { Checkbox } from '@godaddy/antares';export function CheckboxBasic() {  return <Checkbox>One checkbox</Checkbox>;}

Indeterminate

Checkboxes can display an indeterminate state (neither checked nor unchecked), with the use of the isIndeterminate prop, commonly used for "select all" functionality when some but not all child items are selected.

import { Checkbox } from '@godaddy/antares';export function CheckboxIndeterminate() {  return <Checkbox isIndeterminate>Option 1</Checkbox>;}

Checkbox Group

Group multiple checkboxes together with a shared label and description.

Favorite colors
import { Checkbox, CheckboxGroup } from '@godaddy/antares';export function CheckboxGroupBasic() {  return (    <CheckboxGroup label="Favorite colors">      <Checkbox value="blue">Blue</Checkbox>      <Checkbox value="red">Red</Checkbox>      <Checkbox value="green">Green</Checkbox>    </CheckboxGroup>  );}

Controlled

Manage checkbox group state programmatically with controlled component pattern.

Favorite sports
Select your favorite sports
import { useState } from 'react';import { Checkbox, CheckboxGroup } from '@godaddy/antares';export function CheckboxGroupControlled() {  const [selected, setSelected] = useState<string[]>(['baseball', 'tennis']);  return (    <CheckboxGroup      label="Favorite sports"      description="Select your favorite sports"      value={selected}      onChange={setSelected}    >      <Checkbox value="basketball">Basketball</Checkbox>      <Checkbox value="soccer">Soccer</Checkbox>      <Checkbox value="baseball">Baseball</Checkbox>      <Checkbox value="tennis">Tennis</Checkbox>    </CheckboxGroup>  );}

Horizontal Layout

Display checkboxes in a horizontal row instead of vertical stack.

Favorite colors
import { Checkbox, CheckboxGroup } from '@godaddy/antares';export function CheckboxGroupHorizontal() {  return (    <CheckboxGroup label="Favorite colors" direction="row">      <Checkbox value="blue">Blue</Checkbox>      <Checkbox value="red">Red</Checkbox>      <Checkbox value="green">Green</Checkbox>    </CheckboxGroup>  );}

Disabled States

Individual checkboxes within a group can be disabled while others remain interactive.

Favorite colors
Choose your favorite color
import { useState } from 'react';import { Checkbox, CheckboxGroup } from '@godaddy/antares';export function CheckboxGroupDisabled() {  const [selected, setSelected] = useState<string[]>(['purple', 'red']);  return (    <CheckboxGroup      label="Favorite colors"      value={selected}      onChange={setSelected}      errorMessage="At least one color must be selected"      description="Choose your favorite color"      isDisabled    >      <Checkbox value="blue">Blue</Checkbox>      <Checkbox value="red">Red</Checkbox>      <Checkbox value="green">Green</Checkbox>      <Checkbox value="purple">Purple</Checkbox>    </CheckboxGroup>  );}

Required Indicator

Mark a checkbox group as required with visual indicator and validation.

Favorite colors
Choose your favorite color
import { Checkbox, CheckboxGroup } from '@godaddy/antares';export function CheckboxGroupRequired() {  return (    <CheckboxGroup      label="Favorite colors"      errorMessage="At least one color must be selected"      description="Choose your favorite color"      isRequired    >      <Checkbox value="blue">Blue</Checkbox>      <Checkbox value="red">Red</Checkbox>      <Checkbox value="green">Green</Checkbox>    </CheckboxGroup>  );}

Invalid State

Display error state and error message for validation feedback.

Favorite colors
Choose your favorite color
import { Checkbox, CheckboxGroup } from '@godaddy/antares';export function CheckboxGroupInvalid() {  return (    <CheckboxGroup label="Favorite colors" isInvalid description="Choose your favorite color">      <Checkbox value="blue">Blue</Checkbox>      <Checkbox value="red">Red</Checkbox>      <Checkbox value="green">Green</Checkbox>    </CheckboxGroup>  );}

Customization

Data Attributes

Components automatically add data attributes for styling different states:

CheckboxGroup Container: data-invalid, data-disabled, data-required, data-readonly, data-orientation

Checkbox: data-selected, data-indeterminate, data-hovered, data-pressed, data-focused, data-disabled

.my-checkbox-group [data-selected] {
  color: #09757a;
  font-weight: 500;
}

.my-checkbox-group[data-invalid] {
  border-color: #db1802;
}

.my-checkbox-group [data-focused] {
  outline: 2px solid #1976d2;
  outline-offset: 2px;
}

.my-checkbox-group [data-indeterminate] {
  background-color: #1976d2;
}

.my-checkbox-group [data-disabled] {
  opacity: 0.4;
  cursor: not-allowed;
}

Component Customization

Individual components can be styled by passing className props:

<CheckboxGroup label="Select options" className="custom-checkbox-group">
  <Checkbox value="option1" className="custom-checkbox">
    Option 1
  </Checkbox>
  <Checkbox value="option2" className="highlighted-checkbox">
    Option 2
  </Checkbox>
</CheckboxGroup>

Key Features

Indeterminate State

The isIndeterminate prop displays a minus icon to represent a partial selection state. This is useful for "select all" checkboxes when only some items in a collection are selected.

<Checkbox isIndeterminate onChange={handleSelectAll}>
  Select All
</Checkbox>

Group Validation

CheckboxGroup supports validation states and error messages:

  • isRequired: Marks the group as required with visual indicator
  • isInvalid: Shows error state styling
  • errorMessage: Displays validation error text below the group
<CheckboxGroup
  label="Required selection"
  isRequired
  isInvalid={!hasSelection}
  errorMessage="At least one option must be selected"
>
  <Checkbox value="a">Option A</Checkbox>
  <Checkbox value="b">Option B</Checkbox>
</CheckboxGroup>

Direction

Control the layout direction with the direction prop:

  • column (default): Stacks checkboxes vertically
  • row: Arranges checkboxes in a horizontal row
  • column-reverse: Stacks checkboxes vertically in reverse order
  • row-reverse: Arranges checkboxes in reverse order in a horizontal row

Accessibility

Keyboard Navigation

  • Tab: Moves focus to the next/previous checkbox
  • Space: Toggles the focused checkbox
  • Shift + Tab: Moves focus to the previous checkbox

ARIA Support

  • aria-disabled for disabled checkboxes
  • aria-required when selection is required
  • aria-invalid for validation errors
  • Proper labeling with aria-labelledby and aria-describedby

Troubleshooting

Selection Not Updating

// ❌ Wrong: Using both value and defaultValue
<CheckboxGroup value={value} defaultValue={["a"]}>
  <Checkbox value="a">Option A</Checkbox>
</CheckboxGroup>

// ✅ Controlled mode
<CheckboxGroup value={value} onChange={setValue}>
  <Checkbox value="a">Option A</Checkbox>
</CheckboxGroup>

// ✅ Uncontrolled mode
<CheckboxGroup defaultValue={["a"]}>
  <Checkbox value="a">Option A</Checkbox>
</CheckboxGroup>

Indeterminate State Not Updating

The isIndeterminate prop must be explicitly managed - it doesn't automatically reflect parent-child relationships:

// ✅ Correct: Manually manage indeterminate state
const [childSelections, setChildSelections] = React.useState([]);
const allSelected = childSelections.length === totalChildren;
const someSelected = childSelections.length > 0 && !allSelected;

<Checkbox
  isSelected={allSelected}
  isIndeterminate={someSelected}
  onChange={handleSelectAll}
>
  Select All
</Checkbox>

Styling Overrides Not Applying

/* ❌ May not have enough specificity */
.my-custom-checkbox {
  color: red;
}

/* ✅ Use data attributes with className for higher specificity */
.my-checkbox-group [data-selected] {
  color: red;
  font-weight: 600;
}

Keyboard Navigation Not Working

/* ❌ Don't remove focus outlines without replacement */
[data-focused] {
  outline: none;
}

/* ✅ Provide visible focus indicator */
.my-checkbox-group [data-focused] {
  outline: 2px solid #1976d2;
  outline-offset: 2px;
}

Best Practices

When to Use Checkboxes

  • ✅ For selecting multiple independent options
  • ✅ When users can select zero, one, or many items
  • ✅ For toggling settings or features on/off
  • ✅ When all available options should be visible
  • ❌ For mutually exclusive options (use Radio instead)
  • ❌ For simple on/off toggles without labels (use Toggle/Switch instead)

Label Guidelines

  • Use clear, concise labels that describe what selecting the option means
  • Keep labels short (1-5 words when possible)
  • Ensure labels are descriptive without being verbose
  • Place the most commonly selected options first in groups

Validation

Always provide clear error messages and use appropriate validation states:

<CheckboxGroup
  label="Terms and conditions"
  isRequired
  isInvalid={!agreedToTerms}
  errorMessage="You must agree to the terms to continue"
>
  <Checkbox value="terms">I agree to the terms and conditions</Checkbox>
  <Checkbox value="privacy">I agree to the privacy policy</Checkbox>
</CheckboxGroup>

Group Organization

  • Limit checkbox groups to 7-10 options for better usability
  • Use logical ordering (alphabetical, frequency of use, or importance)
  • Consider using CheckboxGroup for related options, even if there are only 2-3
  • Provide a group label that clearly describes the choice being made

Carousel

The Carousel component allows users to cycle through a series of content panels (typically images, cards, or text) in a horizontal or vertical layout. It is commonly used for featured content, product showcases, or testimonials.

Drawer

An overlay panel that slides in from a screen edge, supporting sidebar navigation and bottom sheets.

On this page

InstallationPropsExamplesBasicIndeterminateCheckbox GroupControlledHorizontal LayoutDisabled StatesRequired IndicatorInvalid StateCustomizationData AttributesComponent CustomizationKey FeaturesIndeterminate StateGroup ValidationDirectionAccessibilityKeyboard NavigationARIA SupportTroubleshootingSelection Not UpdatingIndeterminate State Not UpdatingStyling Overrides Not ApplyingKeyboard Navigation Not WorkingBest PracticesWhen to Use CheckboxesLabel GuidelinesValidationGroup Organization