# Radio Group Documentation
Allows users to select a single option from a list of mutually exclusive choices.
This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.
```svelte
<script lang="ts">
import { Label, RadioGroup } from "bits-ui";
</script>
<RadioGroup.Root class="flex flex-col gap-4 text-sm font-medium">
<div
class="text-foreground group flex select-none items-center transition-all"
>
<RadioGroup.Item
id="amazing"
value="amazing"
class="border-border-input bg-background hover:border-dark-40 data-[state=checked]:border-6 data-[state=checked]:border-foreground size-5 shrink-0 cursor-default rounded-full border transition-all duration-100 ease-in-out"
/>
<Label.Root for="amazing" class="pl-3">Amazing</Label.Root>
</div>
<div
class="text-foreground group flex select-none items-center transition-all"
>
<RadioGroup.Item
id="average"
value="average"
class="border-border-input bg-background hover:border-dark-40 data-[state=checked]:border-6 data-[state=checked]:border-foreground size-5 shrink-0 cursor-default rounded-full border transition-all duration-100 ease-in-out"
/>
<Label.Root for="average" class="pl-3">Average</Label.Root>
</div>
<div
class="text-foreground group flex select-none items-center transition-all"
>
<RadioGroup.Item
id="terrible"
value="terrible"
class="border-border-input bg-background hover:border-dark-40 data-[state=checked]:border-6 data-[state=checked]:border-foreground size-5 shrink-0 cursor-default rounded-full border transition-all duration-100 ease-in-out"
/>
<Label.Root for="terrible" class="pl-3">Terrible</Label.Root>
</div>
</RadioGroup.Root>
```
## Structure
```svelte
<script lang="ts">
import { RadioGroup } from "bits-ui";
</script>
<RadioGroup.Root>
<RadioGroup.Item>
{#snippet children({ checked })}
{#if checked}
{/if}
{/snippet}
</RadioGroup.Item>
</RadioGroup.Root>
```
## Reusable Components
It's recommended to use the `RadioGroup` primitives to create your own custom components that can be used throughout your application.
In the example below, we're creating a custom `MyRadioGroup` component that takes in an array of items and renders a radio group with those items along with a [`Label`](/docs/components/label) component for each item.
MyRadioGroup.svelte
```svelte
<script lang="ts">
import { RadioGroup, Label, type WithoutChildrenOrChild, useId } from "bits-ui";
type Item = {
value: string;
label: string;
disabled?: boolean;
};
type Props = WithoutChildrenOrChild<RadioGroup.RootProps> & {
items: Item[];
};
let { value = $bindable(""), ref = $bindable(null), items, ...restProps }: Props = $props();
</script>
<RadioGroup.Root bind:value bind:ref {...restProps}>
{#each items as item}
{@const id = useId()}
<div>
<RadioGroup.Item {id} value={item.value} disabled={item.disabled}>
{#snippet children({ checked })}
{#if checked}
{/if}
{/snippet}
</RadioGroup.Item>
<Label.Root for={id}>{item.label}</Label.Root>
</div>
{/each}
</RadioGroup.Root>
```
You can then use the `MyRadioGroup` component in your application like so:
+page.svelte
```svelte
<script lang="ts">
import MyRadioGroup from "$lib/components/MyRadioGroup.svelte";
const myItems = [
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
{ value: "coconut", label: "Coconut", disabled: true },
];
</script>
<MyRadioGroup items={myItems} name="favoriteFruit" />
```
## Managing Value State
This section covers how to manage the `value` state of the component.
### Two-Way Binding
Use `bind:value` for simple, automatic state synchronization:
```svelte
<script lang="ts">
import { RadioGroup } from "bits-ui";
let myValue = $state("");
</script>
<button onclick={() => (myValue = "A")}> Select A </button>
<RadioGroup.Root bind:value={myValue}>
</RadioGroup.Root>
```
### Fully Controlled
Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.
```svelte
<script lang="ts">
import { RadioGroup } from "bits-ui";
let myValue = $state("");
function getValue() {
return myValue;
}
function setValue(newValue: string) {
myValue = newValue;
}
</script>
<RadioGroup.Root bind:value={getValue, setValue}>
</RadioGroup.Root>
```
## HTML Forms
If you set the `name` prop on the `RadioGroup.Root` component, a hidden input element will be rendered to submit the value of the radio group to a form.
```svelte
<RadioGroup.Root name="favoriteFruit">
</RadioGroup.Root>
```
### Required
To make the hidden input element `required` you can set the `required` prop on the `RadioGroup.Root` component.
```svelte
<RadioGroup.Root required>
</RadioGroup.Root>
```
## Disabling Items
You can disable a radio group item by setting the `disabled` prop to `true`.
```svelte
<RadioGroup.Item value="apple" disabled>Apple</RadioGroup.Item>
```
## Orientation
The `orientation` prop is used to determine the orientation of the radio group, which influences how keyboard navigation will work.
When the `orientation` is set to `'vertical'`, the radio group will navigate through the items using the `ArrowUp` and `ArrowDown` keys. When the `orientation` is set to `'horizontal'`, the radio group will navigate through the items using the `ArrowLeft` and `ArrowRight` keys.
```svelte
<RadioGroup.Root orientation="vertical">
</RadioGroup.Root>
<RadioGroup.Root orientation="horizontal">
</RadioGroup.Root>
```
## API Reference
### RadioGroup.Root
The radio group component used to group radio items under a common name for form submission.
| Property | Type | Description |
| -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `string` | The value of the currently selected radio item. You can bind to this value to control the radio group's value from outside the component.`Default: undefined` |
| `onValueChange` | `function`- (value: string) => void | A callback that is fired when the radio group's value changes.`Default: undefined` |
| `disabled` | `boolean` | Whether or not the radio group is disabled. This prevents the user from interacting with it.`Default: false` |
| `required` | `boolean` | Whether or not the radio group is required.`Default: false` |
| `name` | `string` | The name of the radio group used in form submission. If provided, a hidden input element will be rendered to submit the value of the radio group.`Default: undefined` |
| `loop` | `boolean` | Whether or not the radio group should loop through the items when navigating with the arrow keys.`Default: false` |
| `orientation` | `enum`- 'vertical' \| 'horizontal' | The orientation of the radio group. This will determine how keyboard navigation will work within the component.`Default: 'vertical'` |
| `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` |
| `children` | `Snippet` | The children content to render.`Default: undefined` |
| `child` | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | | Data Attribute | Value | Description |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-orientation` | `enum`- '' | The orientation of the radio group. |
| `data-radio-group-root` | `''` | Present on the root element. |
### RadioGroup.Item
An radio item, which must be a child of the `RadioGroup.Root` component.
| Property | Type | Description |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` required | `string` | The value of the radio item. This should be unique for each radio item in the group.`Default: undefined` |
| `disabled` | `boolean` | Whether the radio item is disabled.`Default: false` |
| `ref` $bindable | `HTMLButtonElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` |
| `children` | `Snippet` | The children content to render.`Default: undefined` |
| `child` | `Snippet`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | | Data Attribute | Value | Description |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-disabled` | `''` | Present when the radio item is disabled. |
| `data-value` | `''` | The value of the radio item. |
| `data-state` | `enum`- '' | The radio item's checked state. |
| `data-orientation` | `enum`- '' | The orientation of the parent radio group. |
| `data-radio-group-item` | `''` | Present on the radio item element. |