## Overview [#overview]
Radio Group lets users choose one option from a mutually exclusive set. Items follow the same surface pattern as Checkbox: the radio item lands at parent +2, hover uses the contextual hover surface, and the checked state uses a brand border with a brand indicator dot.
## Usage [#usage]
```tsx
import { Label } from "@tilt-legal/cubitt-components/label";
import {
RadioGroup,
RadioGroupItem,
} from "@tilt-legal/cubitt-components/radio-group";
```
```tsx
```
## Examples [#examples]
### Sizes [#sizes]
Use the `size` prop on the group to scale all child items.
```tsx
import { Label } from "@tilt-legal/cubitt-components/label";
import {
RadioGroup,
RadioGroupItem,
} from "@tilt-legal/cubitt-components/radio-group";
export default function Example() {
return (
);
}
```
### Disabled [#disabled]
Individual radio items can be disabled.
```tsx
import { Label } from "@tilt-legal/cubitt-components/label";
import {
RadioGroup,
RadioGroupItem,
} from "@tilt-legal/cubitt-components/radio-group";
export default function Example() {
return (
);
}
```
### With Description [#with-description]
Use a wrapped label when a radio option has title and description content.
```tsx
import { Label } from "@tilt-legal/cubitt-components/label";
import {
RadioGroup,
RadioGroupItem,
} from "@tilt-legal/cubitt-components/radio-group";
export default function Example() {
return (
);
}
```
### URL State [#url-state]
Provide `paramName` to sync selection with the current URL.
```tsx
import { Label } from "@tilt-legal/cubitt-components/label";
import {
RadioGroup,
RadioGroupItem,
} from "@tilt-legal/cubitt-components/radio-group";
export default function Example() {
return (
);
}
```
## API Reference [#api-reference]
### RadioGroup [#radiogroup]
| Prop | Type | Default | Description |
| --------------- | ------------------------- | ------- | -------------------------------------------------------- |
| `value` | `string` | - | Controlled selected value. |
| `defaultValue` | `string` | - | Initial selected value when uncontrolled. |
| `onValueChange` | `(value: string) => void` | - | Callback fired when the selected value changes. |
| `disabled` | `boolean` | `false` | Disables all radio items in the group. |
| `name` | `string` | - | Form name shared by the radio items. |
| `required` | `boolean` | `false` | Marks the group as required in forms. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size applied to child items unless an item overrides it. |
| `className` | `string` | - | Additional classes for the group container. |
### URL State Props [#url-state-props]
| Prop | Type | Default | Description |
| --------------------- | --------------------------------- | ------- | ------------------------------------------------------------ |
| `paramName` | `string` | - | URL parameter name. Providing this enables URL state. |
| `paramValue` | `string` | - | Controlled URL parameter value. |
| `onUrlValueChange` | `(value: string \| null) => void` | - | Callback fired when the URL-backed value changes. |
| `paramClearOnDefault` | `boolean` | `true` | Removes the URL parameter when the value equals the default. |
| `paramThrottle` | `number` | - | Throttles URL updates in milliseconds. |
| `paramDebounce` | `number` | - | Debounces URL updates in milliseconds. |
### RadioGroupItem [#radiogroupitem]
| Prop | Type | Default | Description |
| ----------- | ---------------------- | ------- | ------------------------------------------------ |
| `value` | `string` | - | Unique value for the radio item. |
| `disabled` | `boolean` | `false` | Disables this radio item. |
| `size` | `"sm" \| "md" \| "lg"` | - | Item size. Inherits the group size when omitted. |
| `className` | `string` | - | Additional classes for the radio item. |
### Notes [#notes]
* Use `RadioGroupItem` inside `RadioGroup`.
* Wrap `RadioGroupItem` in `Label` when the label text should toggle the item.
* Give each `RadioGroupItem` a unique `value` within its group.