# Button Select (/docs/button-select)
`ButtonSelect` is a single-choice control made of real [`Button`](/docs/button)s, joined like a [`ButtonGroup`](/docs/button-group). Unselected items render in `variant`, and the selected one switches to `selectedVariant`. Every item goes through `Button`, so icons, per-item colors, sizes and the focus ring work as they do on a `Button`.
Use it instead of [`SegmentGroup`](/docs/segment-group) when the options should look like buttons, such as a toolbar or a row of icons. Use it instead of a [`Select`](/docs/select) when the set is small enough to show every option. To pick several values, use [`ButtonMultiSelect`](/docs/button-multi-select).
```tsx
import { ButtonSelect } from "@42-central/ui-react/button-select";
;
```
## Playground [#playground]
## Items [#items]
`data` accepts bare strings, where the value is also the label, or `{ value, label?, startSlot?, endSlot?, disabled?, color?, "aria-label"?, payload? }` objects. You can mix both. Each item also takes an optional `testId`, which defaults to `` `item-${value}` ``. See the [Testing](/docs/testing) guide.
## Variants [#variants]
Two props set the look: `variant` for unselected items (default `light`) and `selectedVariant` for the selected one (default `filled`). Both accept any [`Button`](/docs/button#variants) variant, so you can use a loud pairing for a primary choice or a quiet one for a toolbar.
## Sizes [#sizes]
The five `Button` sizes, `xs` through `xl`.
## Colors [#colors]
`color` sets the palette for every item. It is a `data-color` on the group, so every kit palette works.
### Per-item color [#per-item-color]
An item's own `color` overrides the group palette for that button, whether it is selected or not. This suits status pickers where each option has its own hue.
## Icons [#icons]
`startSlot` and `endSlot` pass through to `Button`.
For an icon-only item, put the icon in `label` and give the item an `aria-label`:
## Deselectable [#deselectable]
By default the group behaves like a radio group: clicking the selected item leaves it selected. With `deselectable`, that click clears the selection and `onChange` receives `null`. The types match: `onChange`'s parameter only includes `null` when `deselectable` is set.
## Custom rendering [#custom-rendering]
Pass `renderItem` to render each item's content yourself. It receives the item, narrowed to your data's values and typed `payload`, along with its live `{ selected, disabled }` state. The item keeps its button, variant and selection wiring. Define the function in a `"use client"` module.
```tsx
"use client";
// item.payload is inferred from `data` — here { readonly count: number } | undefined
const renderCount = (item, { selected }) => (
{item.label}
{item.payload?.count}
);
```
`ButtonSelect` is generic over `data` through a `const` type parameter, like [`Select`](/docs/select#typed-payload): `value` and `onChange` narrow to the literal value union.
## Orientation [#orientation]
`orientation="vertical"` stacks the items in a column.
## Label, description & error [#label-description--error]
`ButtonSelect` wraps itself in [`Field`](/docs/field), so `label`, `description`, `error` and `required` work without extra setup and wire up the `aria-*` relationships. `error` (or `invalid`) draws a red ring around the group.
## Composition [#composition]
For anything `data` can't express, build the group from its parts. `ButtonSelect.Root` holds the value and sets `variant`, `selectedVariant`, `size` and `color` once for every item. Each `ButtonSelect.Item` accepts the same props as a `Button` (`startSlot`, `endSlot`, `color`, `testId`…), except `variant` and `size`, which come from the root. Pass `asChild` to render your own variant-aware control, such as an [`ActionIcon`](/docs/action-icon), in place of the `Button`. See [ButtonMultiSelect's toolbar](/docs/button-multi-select#composition).
The compound root has no `Field` wrapper or `name`. Label it with `aria-label` / `aria-labelledby`.
## Forms [#forms]
`name` renders a hidden input holding the selected value, so the value is sent with a native `