## Overview [#overview]
The **RadioGroup** component allows users to select a single option from a set of mutually exclusive choices. Built on Base UI primitives, it provides a fully accessible radio button group with customizable sizes and flexible styling options.
## Usage [#usage]
```tsx
import { RadioGroup, RadioGroupItem, Label } from "@tilt-legal/cubitt-components/primitives";
```
```tsx
```
Using Cubitt's URL-state hooks, you can sync the radio group selection with the URL by providing a `paramName`:
```tsx
// Selected value synced with ?shipping=express
// Advanced options:
console.log('Selected:', value)}
>
{/* ... */}
```
***
## Examples [#examples]
### Sizes [#sizes]
Radio groups in different sizes.
```tsx
import { RadioGroup, RadioGroupItem, Label } from "@tilt-legal/cubitt-components/primitives";
export default function Example() {
return (
);
}
```
### Disabled [#disabled]
Radio buttons can be individually disabled.
```tsx
import { RadioGroup, RadioGroupItem, Label } from "@tilt-legal/cubitt-components/primitives";
export default function Example() {
return (
);
}
```
### With Description [#with-description]
Radio buttons with additional descriptive text.
```tsx
import { RadioGroup, RadioGroupItem, Label } from "@tilt-legal/cubitt-components/primitives";
export default function Example() {
return (
Perfect for personal projects and small teams.
Advanced features for growing businesses.
Custom solutions for large organizations.
);
}
```
### Card Style [#card-style]
Radio buttons styled as interactive cards.
```tsx
import { RadioGroup, RadioGroupItem } from "@tilt-legal/cubitt-components/primitives";
export default function Example() {
return (
);
}
```
### URL State [#url-state]
Sync radio group selection with the URL. Try selecting an option and refreshing the page.
```tsx
import { RadioGroup, RadioGroupItem, Label } from "@tilt-legal/cubitt-components/primitives";
export default function Example() {
return (
);
}
```
***
## API Reference [#api-reference]
### RadioGroup [#radiogroup]
The root container component that manages the radio button group.
| Prop | Type | Default | Description |
| --------------- | ------------------------- | ------- | ------------------------------------------------------------ |
| `value` | `string` | - | The controlled value of the selected radio button. |
| `defaultValue` | `string` | - | The default value when uncontrolled. |
| `onValueChange` | `(value: string) => void` | - | Callback fired when the selected value changes. |
| `disabled` | `boolean` | `false` | Whether all radio buttons in the group are disabled. |
| `name` | `string` | - | The name attribute for the radio group (used in forms). |
| `required` | `boolean` | `false` | Whether the radio group is required in a form. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size variant applied to all child RadioGroupItem components. |
| `className` | `string` | - | Additional CSS classes for the radio group container. |
| `data-slot` | `string` | - | Data attribute for styling and testing hooks. |
#### URL State Props [#url-state-props]
When provided with a `paramName`, the radio group will sync its selection with URL parameters via TanStack Router search params.
| Prop | Type | Default | Description |
| --------------------- | ------------------------- | ------- | ---------------------------------------------------------------------------- |
| `paramName` | `string` | — | URL parameter name for syncing state with URL. Enables URL state management. |
| `paramValue` | `string` | — | Controlled value for the URL parameter. |
| `onUrlValueChange` | `(value: string) => void` | — | Callback when URL parameter value changes. |
| `paramClearOnDefault` | `boolean` | `true` | Remove URL param when value equals default. |
| `paramThrottle` | `number` | — | Throttle URL updates in milliseconds. |
| `paramDebounce` | `number` | — | Debounce URL updates in milliseconds. |
### RadioGroupItem [#radiogroupitem]
Individual radio button within a RadioGroup.
| Prop | Type | Default | Description |
| ----------- | ---------------------- | ------- | ---------------------------------------------------------------- |
| `value` | `string` | - | The unique value for this radio button (required). |
| `id` | `string` | - | The id attribute for the radio button (used with Label htmlFor). |
| `disabled` | `boolean` | `false` | Whether this specific radio button is disabled. |
| `size` | `"sm" \| "md" \| "lg"` | - | Size variant (inherits from RadioGroup if not specified). |
| `className` | `string` | - | Additional CSS classes for the radio button. |
| `data-slot` | `string` | | Data attribute for styling and testing hooks. |
### Notes [#notes]
* Radio buttons must be used within a `RadioGroup` component
* Each `RadioGroupItem` should have a unique `value` prop within its group
* Use the `id` prop on `RadioGroupItem` and `htmlFor` on `Label` for proper label association
* The `size` prop on `RadioGroup` automatically applies to all child items via Context
* Individual `RadioGroupItem` components can override the group's size if needed