# Choice Box (/forms/choice-box)





<ComponentPreview name="choicebox-preskok-demo" description="Multiple selection choice box with car package options." />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger id="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger id="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent id="cli">
    ```bash
    npx shadcn@latest add @preskok/choice-box
    ```
  </TabsContent>

  <TabsContent id="manual">
    <Steps>
      <Step>
        Copy and paste the following code into your project.

        <ComponentSource name="choice-box" title="registry/preskok/ui/preskok-ui/choice-box.tsx" />
      </Step>

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import {
  ChoiceBox,
  ChoiceBoxDescription,
  ChoiceBoxItem,
  ChoiceBoxLabel,
} from "@/components/ui/preskok-ui/choice-box"

export function ChoiceBoxExample() {
  return (
    <ChoiceBox aria-label="Select car packages" selectionMode="multiple">
      <ChoiceBoxItem
        textValue="sedan"
        label="Sedan"
        description="Comfortable family car with excellent fuel economy."
      />
      <ChoiceBoxItem
        textValue="suv"
        label="SUV"
        description="Versatile vehicle with enhanced cargo space and off-road capability."
      />
      <ChoiceBoxItem
        textValue="luxury"
        label="Luxury"
        description="Premium features with leather interior and advanced technology package."
      />
    </ChoiceBox>
  )
}
```

## Components [#components]

### ChoiceBox [#choicebox]

The root container component for the choice box.

| Prop            | Type                              | Default    | Description                         |
| --------------- | --------------------------------- | ---------- | ----------------------------------- |
| `columns`       | `1 \| 2 \| 3 \| 4 \| 5 \| 6`      | `1`        | Number of columns for grid layout   |
| `gap`           | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `0`        | Gap between items                   |
| `selectionMode` | `"single" \| "multiple"`          | `"single"` | Selection mode                      |
| `isReadOnly`    | `boolean`                         | `false`    | Whether the choice box is read-only |
| `className`     | `string`                          | -          | Additional CSS classes              |

All standard `GridList` props from React Aria Components are also supported.

### ChoiceBoxItem [#choiceboxitem]

An individual choice item within the choice box.

| Prop          | Type     | Default | Description                                |
| ------------- | -------- | ------- | ------------------------------------------ |
| `label`       | `string` | -       | Label text for the item                    |
| `description` | `string` | -       | Description text displayed below the label |
| `className`   | `string` | -       | Additional CSS classes                     |

All standard `GridListItem` props from React Aria Components are also supported.

### ChoiceBoxLabel [#choiceboxlabel]

The label text component for choice items.

| Prop        | Type     | Default | Description            |
| ----------- | -------- | ------- | ---------------------- |
| `className` | `string` | -       | Additional CSS classes |

All standard `Text` props from React Aria Components are also supported.

### ChoiceBoxDescription [#choiceboxdescription]

The description text component for choice items.

| Prop        | Type     | Default | Description            |
| ----------- | -------- | ------- | ---------------------- |
| `className` | `string` | -       | Additional CSS classes |

All standard `Text` props from React Aria Components are also supported.

## Examples [#examples]

<ComponentPreview name="choicebox-preskok-demo" description="Single selection, grid layout, controlled multiple selection, descriptions, and disabled items." />