# 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. Copy Page ```svelte
Amazing
Average
Terrible
``` ## Structure ```svelte {#snippet children({ checked })} {#if checked} {/if} {/snippet} ``` ## 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 {#each items as item} {@const id = useId()}
{#snippet children({ checked })} {#if checked} {/if} {/snippet} {item.label}
{/each} ``` You can then use the `MyRadioGroup` component in your application like so: +page.svelte ```svelte ``` ## 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 ``` ### 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 ``` ## 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 ``` ### Required To make the hidden input element `required` you can set the `required` prop on the `RadioGroup.Root` component. ```svelte ``` ## Disabling Items You can disable a radio group item by setting the `disabled` prop to `true`. ```svelte Apple ``` ## 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 ``` ## Examples ### Readonly When a radio group is readonly, users can focus and navigate through the items but cannot change the selection. This is useful for displaying information that should be visible but not editable. Expand Code ```svelte
Amazing
Average
Terrible
``` ```svelte ``` ### Disabled When a radio group is disabled, users cannot interact with it at all. The entire group becomes non-focusable and non-interactive. Expand Code ```svelte
Amazing
Average
Terrible
``` ```svelte ``` ## API Reference ### RadioGroup.Root The radio group component used to group radio items under a common name for form submission. | Property | Type | Description | Details | | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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'` | | | `readonly` | `boolean` | Whether or not the radio group is readonly. When readonly, users can focus and navigate through items but cannot change the value.`Default: false` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `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 | Details | | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data-orientation` | `enum`- 'vertical' \| 'horizontal' | The orientation of the radio group. | | | `data-disabled` | `''` | Present when the radio group is disabled. | | | `data-readonly` | `''` | Present when the radio group is readonly. | | | `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 | Details | | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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: null` | | | `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 | Details | | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data-disabled` | `''` | Present when the radio item is disabled. | | | `data-readonly` | `''` | Present when the radio group is readonly. | | | `data-value` | `''` | The value of the radio item. | | | `data-state` | `enum`- 'checked' \| 'unchecked' | The radio item's checked state. | | | `data-orientation` | `''` | The orientation of the parent radio group. | | | `data-radio-group-item` | `''` | Present on the radio item element. | | [Previous Progress](/docs/components/progress) [Next Range Calendar](/docs/components/range-calendar)