 <CheckboxGroup.Root defaultValue={['1']}>
  <CheckboxGroup.Item value="1">Option 1</CheckboxGroup.Item>
  <CheckboxGroup.Item value="2">Option 2</CheckboxGroup.Item>
  <CheckboxGroup.Item value="3">Option 3</CheckboxGroup.Item>
</CheckboxGroup.Root>

API Reference

This component inherits props from the Checkbox Group component and supports common margin props.

Root

Contains all the parts of a checkbox group.

Prop	Type	Default	Description
`asChild`	`boolean`	`false`	Merge root props onto immediate child
`defaultValue`	`string[]`		Default selected values
`value`	`string[]`		Controlled selected values
`size`	`"1" \| "2" \| "3"`	`"2"`	Checkbox size
`variant`	`"classic" \| "surface" \| "soft"`	`"surface"`	Visual style variant
`color`	`"gray" \| "purple"`	`"purple"`	Color theme

Item

An item in the group that can be checked.

Prop	Type	Default	Description
`value`	`string`		Unique value for this item (required)
`disabled`	`boolean`	`false`	Disable the checkbox

Examples

Basic group

Use a checkbox group when needing to select multiple independent options from a list, choosing any combination including none, some, or all available options.

Password rules

At least one uppercase letterAt least one lowercase letterAt least one numberAt least one special character

 <Flex direction="column" gap="2" maxWidth="400px">
  <Text size="2" weight="bold">
    Password rules
  </Text>

  <CheckboxGroup.Root defaultValue={['uppercase', 'lowercase']}>
    <CheckboxGroup.Item value="uppercase">
      At least one uppercase letter
    </CheckboxGroup.Item>
    <CheckboxGroup.Item value="lowercase">
      At least one lowercase letter
    </CheckboxGroup.Item>
    <CheckboxGroup.Item value="number">At least one number</CheckboxGroup.Item>
    <CheckboxGroup.Item value="special">
      At least one special character
    </CheckboxGroup.Item>
  </CheckboxGroup.Root>
</Flex>

With helper text

Add helper text to provide additional context about the checkbox group.

Password rules

At least one uppercase letterAt least one lowercase letterAt least one numberAt least one special character

Select which rules to enforce for new passwords.

 <Flex direction="column" gap="2" maxWidth="400px">
  <Text size="2" weight="bold">
    Password rules
  </Text>

  <CheckboxGroup.Root defaultValue={['uppercase', 'number']}>
    <CheckboxGroup.Item value="uppercase">
      At least one uppercase letter
    </CheckboxGroup.Item>
    <CheckboxGroup.Item value="lowercase">
      At least one lowercase letter
    </CheckboxGroup.Item>
    <CheckboxGroup.Item value="number">At least one number</CheckboxGroup.Item>
    <CheckboxGroup.Item value="special">
      At least one special character
    </CheckboxGroup.Item>
  </CheckboxGroup.Root>

  <Text size="2" color="gray">
    Select which rules to enforce for new passwords.
  </Text>
</Flex>

With validation message

Display validation messages along with helper text to provide feedback and context.

Password rules

At least one uppercase letterAt least one lowercase letterAt least one numberAt least one special character

Please select at least one password rule.Select which rules to enforce for new passwords.

 <Flex direction="column" gap="2" maxWidth="400px">
  <Text size="2" weight="bold">
    Password rules
  </Text>

  <CheckboxGroup.Root>
    <CheckboxGroup.Item value="uppercase">
      At least one uppercase letter
    </CheckboxGroup.Item>
    <CheckboxGroup.Item value="lowercase">
      At least one lowercase letter
    </CheckboxGroup.Item>
    <CheckboxGroup.Item value="number">At least one number</CheckboxGroup.Item>
    <CheckboxGroup.Item value="special">
      At least one special character
    </CheckboxGroup.Item>
  </CheckboxGroup.Root>

  <Text size="2" color="red">
    Please select at least one password rule.
  </Text>

  <Text size="2" color="gray">
    Select which rules to enforce for new passwords.
  </Text>
</Flex>

Size

Use the size prop to control the checkbox size.

 <Flex direction="column" gap="4">
  <CheckboxGroup.Root size="1" defaultValue={['1']}>
    <CheckboxGroup.Item value="1">Size 1</CheckboxGroup.Item>
    <CheckboxGroup.Item value="2">Size 1</CheckboxGroup.Item>
  </CheckboxGroup.Root>

  <CheckboxGroup.Root size="2" defaultValue={['1']}>
    <CheckboxGroup.Item value="1">Size 2</CheckboxGroup.Item>
    <CheckboxGroup.Item value="2">Size 2</CheckboxGroup.Item>
  </CheckboxGroup.Root>

  <CheckboxGroup.Root size="3" defaultValue={['1']}>
    <CheckboxGroup.Item value="1">Size 3</CheckboxGroup.Item>
    <CheckboxGroup.Item value="2">Size 3</CheckboxGroup.Item>
  </CheckboxGroup.Root>
</Flex>

Disabled

Use the native disabled attribute to create disabled checkboxes within a group.

Password rules

At least one uppercase letterAt least one lowercase letterAt least one number (required)At least one special character

 <Flex direction="column" gap="2" maxWidth="400px">
  <Text size="2" weight="bold">
    Password rules
  </Text>

  <CheckboxGroup.Root defaultValue={['uppercase', 'lowercase', 'number']}>
    <CheckboxGroup.Item value="uppercase">
      At least one uppercase letter
    </CheckboxGroup.Item>
    <CheckboxGroup.Item value="lowercase">
      At least one lowercase letter
    </CheckboxGroup.Item>
    <CheckboxGroup.Item value="number" disabled>
      At least one number (required)
    </CheckboxGroup.Item>
    <CheckboxGroup.Item value="special" disabled>
      At least one special character
    </CheckboxGroup.Item>
  </CheckboxGroup.Root>
</Flex>