Checkbox Group

Groups related checkboxes with a shared label, hint text, and validation state.

import {CheckboxGroup} from "@qualcomm-ui/react/checkbox-group"

Examples

Simple

Use the simple API to create a checkbox group using minimal markup.

If you omit the label, you should provide an aria-label prop to keep your group accessible.

Notifications

EmailSMSPush

Select at least one

<CheckboxGroup hint="Select at least one" label="Notifications">
  <Checkbox label="Email" />
  <Checkbox label="SMS" />
  <Checkbox label="Push" />
</CheckboxGroup>

Composite

Use the composite API for granular control over the group structure.

Notifications

EmailSMSPush

Select at least one

<CheckboxGroup.Root>
  <CheckboxGroup.Label>Notifications</CheckboxGroup.Label>
  <CheckboxGroup.Items>
    <Checkbox label="Email" />
    <Checkbox label="SMS" />
    <Checkbox label="Push" />
  </CheckboxGroup.Items>
  <CheckboxGroup.Hint>Select at least one</CheckboxGroup.Hint>
</CheckboxGroup.Root>

Size

The size prop controls the size of child checkboxes. Available sizes are sm, md (default), and lg.

import type {ReactElement} from "react"

import {Checkbox} from "@qualcomm-ui/react/checkbox"
import {CheckboxGroup} from "@qualcomm-ui/react/checkbox-group"

export function CheckboxGroupSizeDemo(): ReactElement {
  return (
    <div className="flex flex-row gap-8">
      <CheckboxGroup label="Small" size="sm">
        <Checkbox label="Email" />
        <Checkbox label="SMS" />
      </CheckboxGroup>
      <CheckboxGroup label="Medium" size="md">
        <Checkbox label="Email" />
        <Checkbox label="SMS" />
      </CheckboxGroup>
      <CheckboxGroup label="Large" size="lg">
        <Checkbox label="Email" />
        <Checkbox label="SMS" />
      </CheckboxGroup>
    </div>
  )
}

Orientation

Use the orientation prop to control the layout direction of the group. Options include:

vertical: checkboxes are laid out in a column (default).
horizontal: checkboxes are laid out in a row.

Notifications

EmailSMSPush

<CheckboxGroup label="Notifications" orientation="horizontal">
  <Checkbox label="Email" />
  <Checkbox label="SMS" />
  <Checkbox label="Push" />
</CheckboxGroup>

Indented

Set indented to add padding at the start of the group.

Notifications

EmailSMSPush

<CheckboxGroup indented label="Notifications">
  <Checkbox label="Email" />
  <Checkbox label="SMS" />
  <Checkbox label="Push" />
</CheckboxGroup>

Hint

Use hint to add additional guidance or context to the user below the group.

Notifications

EmailSMSPush

Select at least one

<CheckboxGroup hint="Select at least one" label="Notifications">
  <Checkbox label="Email" />
  <Checkbox label="SMS" />
  <Checkbox label="Push" />
</CheckboxGroup>

Error Text

Set invalid and errorText to display validation errors. The error text replaces the hint when present.

Notifications

EmailSMS

Select at least one option

<CheckboxGroup
  errorText="Select at least one option"
  invalid
  label="Notifications"
>
  <Checkbox label="Email" />
  <Checkbox label="SMS" />
</CheckboxGroup>

API

<CheckboxGroup>

Prop	Type	Default
children ^* React children prop.	ReactNode
errorText Error message displayed when invalid.	string
hint Helper text displayed below items.	string
indented Adds padding at the start of the items container.	boolean
invalid Marks the group as invalid.	boolean
label Group label text.	string
orientation Layout direction for items.	\| 'vertical' \| 'horizontal'	'vertical'
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
size The size of the group items.	\| 'sm' \| 'md' \| 'lg'	'md'

children

Type

ReactNode

Description

React children prop.

errorText

Type

string

Description

Error message displayed when invalid.

hint

Type

string

Description

Helper text displayed below items.

indented

Type

boolean

Description

Adds padding at the start of the items container.

invalid

Type

boolean

Description

Marks the group as invalid.

label

Type

string

Description

Group label text.

orientation

Type

| 'vertical'
| 'horizontal'

Description

Layout direction for items.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

size

Type

| 'sm'
| 'md'
| 'lg'

Description

The size of the group items.

Composite API

<CheckboxGroup.Root>

Root container for the field group. Renders a <fieldset> element by default.

Prop	Type	Default
children React children prop.	ReactNode
indented Adds padding at the start of the items container.	boolean
invalid Marks the group as invalid.	boolean
orientation Layout direction for items.	\| 'vertical' \| 'horizontal'	'vertical'
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
size The size of the group items.	\| 'sm' \| 'md' \| 'lg'	'md'

children

Type

ReactNode

Description

React children prop.

indented

Type

boolean

Description

Adds padding at the start of the items container.

invalid

Type

boolean

Description

Marks the group as invalid.

orientation

Type

| 'vertical'
| 'horizontal'

Description

Layout direction for items.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

size

Type

| 'sm'
| 'md'
| 'lg'

Description

The size of the group items.

Attribute / Property	Value
`className`	'qui-field-group__root'
`data-invalid`
`data-part`	'root'
`data-scope`	'field-group'

className

Value

'qui-field-group__root'

data-invalid

Value

data-part

Value

'root'

data-scope

Value

'field-group'

<CheckboxGroup.Label>

Label for the field group. Renders a <legend> element by default.

Prop	Type
children React children prop.	ReactNode
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-field-group__label'
`data-part`	'label'
`data-scope`	'field-group'

<CheckboxGroup.Items>

Container for the field group items. Renders a <div> element by default.

Prop	Type
children React children prop.	ReactNode
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-field-group__items'
`data-indented`
`data-orientation`	\| 'vertical' \| 'horizontal'
`data-part`	'items'
`data-scope`	'field-group'
`data-size`	\| 'sm' \| 'md' \| 'lg'

className

Value

'qui-field-group__items'

data-indented

Value

data-orientation

Value

| 'vertical'
| 'horizontal'

data-part

Value

'items'

data-scope

Value

'field-group'

data-size

Value

| 'sm'
| 'md'
| 'lg'

<CheckboxGroup.Hint>

Hint text for the field group. Renders a <div> element by default.

Prop	Type
children React children prop.	ReactNode
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-field-group__hint'
`data-part`	'hint'
`data-scope`	'field-group'

<CheckboxGroup.ErrorText>

Error text for the field group. Renders a <div> element by default.

Prop	Type	Default
children React children prop.	ReactNode
icon An icon to display next to the error text.	\| LucideIcon \| ReactNode	<CircleAlert />
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

icon

Type

| LucideIcon
| ReactNode

Description

An icon to display next to the error text.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-field-group__error-text'
`data-part`	'error-text'
`data-scope`	'field-group'

className

Value

'qui-field-group__error-text'

data-part

Value

'error-text'

data-scope

Value

'field-group'

Checkbox

Combobox