# ChipGroup

> A set of chips that act as toggle buttons (`aria-pressed`) in a `fieldset` (a named group): pick several (`type="multiple"`, default) or one (`type="single"`).

Source: https://ui.jcsoftdev.com/docs/components/chip-group

A set of chips that act as toggle buttons (`aria-pressed`) in a `fieldset` (a named group): pick several
(`type="multiple"`, default) or one (`type="single"`). Arrow keys, Home and End move between
chips and Space or Enter toggles; the group works inside `Field` (named from its label,
described by its hint and error) and submits one hidden input per selected value when named.

## Import

```ts
import { ChipGroup } from "@jcsoftdev/ui/forms";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/forms/chip-group`.

## Usage

```tsx
<ChipGroup options={options} aria-label="Subjects" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `"single" \| "multiple"` |  | Any number of chips can be on. This is the default. At most one chip is on. |
| `value` | `string \| string[]` |  |  |
| `defaultValue` | `string \| string[]` |  |  |
| `onValueChange` | `((value: string[]) => void) \| ((value: string) => void)` |  |  |
| `options` * | `readonly ChipGroupOption[]` |  |  |
| `disabled` | `boolean` |  |  |
| `name` | `string` |  | Form field name: a hidden input per selected value. |
| `invalid` | `boolean` |  | Marks the group invalid (also set by `Field` through `aria-invalid`). |
| `id` | `string` |  | Set by `Field`; the group is named from the field's label. |
| `aria-label` | `string` |  |  |
| `aria-labelledby` | `string` |  |  |
| `aria-describedby` | `string` |  |  |
| `aria-invalid` | `boolean \| "true" \| "false"` |  |  |
| `size` | `"sm" \| "md"` |  | Minimum chip height: `sm` (default) is 30px (`--control-height-sm`), `md` 38px (`--control-height-md`), the heights of `Button` and `Input` of the same size. |
| `className` | `string` |  |  |
| `classNames` | `Partial<Record<ChipGroupPart, string>>` |  | Per-part classes merged with `cn`; consumer classes win. `className` still targets the root. |

`*` marks a required prop.

## Storybook stories

- [Multiple](/storybook/?path=/story/forms-chipgroup--multiple)
- [Keyboard Roves And Toggles](/storybook/?path=/story/forms-chipgroup--keyboard-roves-and-toggles)
- [Tab Enters At First Chip When None Selected](/storybook/?path=/story/forms-chipgroup--tab-enters-at-first-chip-when-none-selected)
- [Single](/storybook/?path=/story/forms-chipgroup--single)
- [Single With Deselect](/storybook/?path=/story/forms-chipgroup--single-with-deselect)
- [Controlled](/storybook/?path=/story/forms-chipgroup--controlled)
- [Inside Field](/storybook/?path=/story/forms-chipgroup--inside-field)
- [Submits Hidden Inputs](/storybook/?path=/story/forms-chipgroup--submits-hidden-inputs)
- [Disabled](/storybook/?path=/story/forms-chipgroup--disabled)

## Source

`packages/ui/src/forms/chip-group/chip-group.tsx`