Radio Group

Provides shared state to a series of radio buttons.

Best apple

Fuji Gala Granny Smith

<script lang="ts">
	import { Radio } from '@sveltery/base/radio';
	import { RadioGroup } from '@sveltery/base/radio-group';

	const id = $props.id();
</script>

<RadioGroup
	aria-labelledby={id}
	defaultValue="fuji-apple"
	class="flex flex-col items-start gap-1 text-neutral-950 dark:text-white"
>
	<div class="text-sm font-bold" {id}>Best apple</div>

	<label class="flex items-center gap-2 text-sm font-normal text-neutral-950 dark:text-white">
		<Radio.Root
			value="fuji-apple"
			class="flex size-4 shrink-0 items-center justify-center border rounded-full p-0 border-neutral-950 bg-white text-white dark:border-white dark:bg-neutral-950 dark:text-neutral-950 data-checked:bg-neutral-950 data-checked:text-white dark:data-checked:bg-white dark:data-checked:text-neutral-950 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
		>
			<Radio.Indicator
				class="flex items-center justify-center data-unchecked:hidden before:size-2 before:rounded-full before:bg-current"
			/>
		</Radio.Root>
		Fuji
	</label>

	<label class="flex items-center gap-2 text-sm font-normal text-neutral-950 dark:text-white">
		<Radio.Root
			value="gala-apple"
			class="flex size-4 shrink-0 items-center justify-center border rounded-full p-0 border-neutral-950 bg-white text-white dark:border-white dark:bg-neutral-950 dark:text-neutral-950 data-checked:bg-neutral-950 data-checked:text-white dark:data-checked:bg-white dark:data-checked:text-neutral-950 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
		>
			<Radio.Indicator
				class="flex items-center justify-center data-unchecked:hidden before:size-2 before:rounded-full before:bg-current"
			/>
		</Radio.Root>
		Gala
	</label>

	<label class="flex items-center gap-2 text-sm font-normal text-neutral-950 dark:text-white">
		<Radio.Root
			value="granny-smith-apple"
			class="flex size-4 shrink-0 items-center justify-center border rounded-full p-0 border-neutral-950 bg-white text-white dark:border-white dark:bg-neutral-950 dark:text-neutral-950 data-checked:bg-neutral-950 data-checked:text-white dark:data-checked:bg-white dark:data-checked:text-neutral-950 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
		>
			<Radio.Indicator
				class="flex items-center justify-center data-unchecked:hidden before:size-2 before:rounded-full before:bg-current"
			/>
		</Radio.Root>
		Granny Smith
	</label>
</RadioGroup>

Usage guidelines

Form controls must have an accessible name: It can be created using <label> elements, or the Field and Fieldset components. See Labeling a radio group and the forms guide.

Anatomy

Import the component and assemble its parts:

Anatomy

<script lang="ts">
	import { Radio } from '@sveltery/base/radio';
	import { RadioGroup } from '@sveltery/base/radio-group';
</script>

<RadioGroup>
	<Radio.Root>
		<Radio.Indicator />
	</Radio.Root>
</RadioGroup>

Examples

Labeling a radio group

Label the group with aria-labelledby and a sibling label element:

Using aria-labelledby to label a radio group

<div id="storage-type-label">Storage type</div>
<RadioGroup aria-labelledby="storage-type-label">
	<!-- ... -->
</RadioGroup>

An enclosing <label> is the simplest labeling pattern for each radio:

Using an enclosing label to label a radio button

<label>
	<Radio.Root value="ssd" />
	SSD
</label>

Rendering as a native button

By default, <Radio.Root> renders a <span> element to support enclosing labels. Prefer rendering each radio as a native button when using sibling labels (for/id).

Sibling label pattern with a native button

<div id="storage-type">Storage type</div>
<RadioGroup defaultValue="ssd" aria-labelledby="storage-type">
	<div>
		<label for="storage-type-ssd">SSD</label>
		<Radio.Root value="ssd" id="storage-type-ssd" nativeButton>
			{#snippet render(props, state, children)}
				<button type="button" {...props}>{@render children?.()}</button>
			{/snippet}
			<Radio.Indicator />
		</Radio.Root>
	</div>
</RadioGroup>

Native buttons with wrapping labels are supported by using the render snippet to avoid invalid HTML, so the hidden input is placed outside the label:

Render snippet

<div id="storage-type">Storage type</div>
<RadioGroup defaultValue="ssd" aria-labelledby="storage-type">
	<Radio.Root value="ssd" nativeButton>
		{#snippet render(props, state, children)}
			<label>
				<button type="button" {...props}>{@render children?.()}</button>
				SSD
			</label>
		{/snippet}
	</Radio.Root>
</RadioGroup>

Form integration

Use Field and Fieldset for group labeling and form integration:

Using Radio Group in a form

<Form>
	<Field.Root name="storageType">
		<Fieldset.Root>
			{#snippet render(props, state, children)}
				<RadioGroup {...props}>{@render children?.()}</RadioGroup>
			{/snippet}
			<Fieldset.Legend>Storage type</Fieldset.Legend>
			<Field.Item>
				<Field.Label>
					<Radio.Root value="ssd" />
					SSD
				</Field.Label>
			</Field.Item>
			<Field.Item>
				<Field.Label>
					<Radio.Root value="hdd" />
					HDD
				</Field.Label>
			</Field.Item>
		</Fieldset.Root>
	</Field.Root>
</Form>

API reference

RadioGroup

value Value —

Name: value
Description: The selected radio's value. Use bind:value to share it with the parent. Hold the value with eventDetails.cancel() to keep a click from sticking. Object values are compared with ===. Store them with $state.raw.
Type: Value
Binding: bind:value

defaultValue Value undefined

Name: defaultValue
Description: The value an empty value starts from.
Type: Value
Default: undefined

disabled boolean | null false

Name: disabled
Description: Whether the group should ignore user interaction.
Type: boolean | null
Default: false

readonly boolean | null false

Name: readonly
Description: Whether the user should be unable to select a different radio button in the group.
Type: boolean | null
Default: false

required boolean | null false

Name: required
Description: Whether the user must choose a value before submitting a form.
Type: boolean | null
Default: false

name string | null —

Name: name
Description: Identifies the field when a form is submitted.
Type: string | null

form string | null —

Name: form
Description: Identifies the form that owns the radio inputs. Useful when the radio group is rendered outside the form.
Type: string | null

onValueChange function —

Name: onValueChange
Description: Called before the value changes. Call eventDetails.cancel() to veto it.
Type: (value: Value, eventDetails: RadioGroupChangeEventDetails) => void

render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: RadioGroupState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <div>. Spread props onto the host element.
Type: Snippet<[props: HTMLAttributes<HTMLDivElement>, state: RadioGroupState, children: Snippet | undefined]>

disabled boolean

Name: disabled
Description: Whether the group should ignore user interaction.
Type: boolean

readOnly boolean

Name: readOnly
Description: Whether the user should be unable to select a different radio.
Type: boolean

required boolean

Name: required
Description: Whether the user must choose a value before submitting a form.
Type: boolean

touched boolean

Name: touched
Description: Whether the field has been touched.
Type: boolean

dirty boolean

Name: dirty
Description: Whether the field value has changed from its initial value.
Type: boolean

valid boolean | null

Name: valid
Description: Whether the field is valid. null means validity is not known yet.
Type: boolean | null

filled boolean

Name: filled
Description: Whether the field has a value.
Type: boolean

focused boolean

Name: focused
Description: Whether the field is focused.
Type: boolean

data-disabled

Present when the radio group is disabled.

Attribute	Description	-
`data-disabled`	Present when the radio group is disabled.

Root

Represents the radio button itself. Renders a <span> and a hidden radio beside it.

value^* unknown —

Name: value
Description: The unique identifying value of the radio. Without a radio group, the radio is selected only when this is ''.
Type: unknown

disabled boolean | null false

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | null
Default: false

readonly boolean | null false

Name: readonly
Description: Whether the user should be unable to select the radio button.
Type: boolean | null
Default: false

required boolean | null false

Name: required
Description: Whether the user must choose a value before submitting a form.
Type: boolean | null
Default: false

nativeButton boolean false

Name: nativeButton
Description: Whether the host is a native <button>. Set true and render a <button>. The id is then applied to that button instead of the hidden input.
Type: boolean
Default: false

id string | null —

Name: id
Description: The id of the hidden input. When nativeButton is true, the id is applied to the root element instead.
Type: string | null

onclick MouseEventHandler<HTMLElement> | null —

Name: onclick
Description: Runs before the radio's click handler. Call event.preventDefault() to skip it.
Type: MouseEventHandler<HTMLElement> | null

render Snippet<[props: RadioHostProps, state: RadioRootState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <span>. Spread props onto the host element.
Type: Snippet<[props: RadioHostProps, state: RadioRootState, children: Snippet | undefined]>

checked boolean

Name: checked
Description: Whether the radio button is currently selected.
Type: boolean

disabled boolean

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean

readOnly boolean

Name: readOnly
Description: Whether the user should be unable to select the radio button.
Type: boolean

required boolean

Name: required
Description: Whether the user must choose a value before submitting a form.
Type: boolean

touched boolean

Name: touched
Description: Whether the field has been touched.
Type: boolean

dirty boolean

Name: dirty
Description: Whether the field value has changed from its initial value.
Type: boolean

valid boolean | null

Name: valid
Description: Whether the field is valid. null means validity is not known yet.
Type: boolean | null

filled boolean

Name: filled
Description: Whether the field has a value.
Type: boolean

focused boolean

Name: focused
Description: Whether the field is focused.
Type: boolean

data-checked

Present when the radio is checked.

data-unchecked

Present when the radio is not checked.

data-disabled

Present when the radio is disabled.

data-readonly

Present when the radio is readonly.

data-required

Present when the radio is required.

data-valid

Present when the radio is in a valid state (when wrapped in Field.Root).

data-invalid

Present when the radio is in an invalid state (when wrapped in Field.Root).

data-dirty

Present when the radio's value has changed (when wrapped in Field.Root).

data-touched

Present when the radio has been touched (when wrapped in Field.Root).

data-filled

Present when the radio is checked (when wrapped in Field.Root).

data-focused

Present when the radio is focused (when wrapped in Field.Root).

Attribute	Description	-
`data-checked`	Present when the radio is checked.
`data-unchecked`	Present when the radio is not checked.
`data-disabled`	Present when the radio is disabled.
`data-readonly`	Present when the radio is readonly.
`data-required`	Present when the radio is required.
`data-valid`	Present when the radio is in a valid state (when wrapped in Field.Root).
`data-invalid`	Present when the radio is in an invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the radio's value has changed (when wrapped in Field.Root).
`data-touched`	Present when the radio has been touched (when wrapped in Field.Root).
`data-filled`	Present when the radio is checked (when wrapped in Field.Root).
`data-focused`	Present when the radio is focused (when wrapped in Field.Root).

Indicator

Indicates whether the radio button is selected. Renders a <span> while selected or kept mounted.

keepMounted boolean false

Name: keepMounted
Description: Whether to keep the indicator in the DOM when the radio is not selected.
Type: boolean
Default: false

render Snippet<[props: HTMLAttributes<HTMLSpanElement>, state: RadioIndicatorState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <span>. Spread props onto the host element.
Type: Snippet<[props: HTMLAttributes<HTMLSpanElement>, state: RadioIndicatorState, children: Snippet | undefined]>

transitionStatus RadioIndicatorPhase

Name: transitionStatus
Description: Indicator motion phase.
Type: RadioIndicatorPhase

checked boolean

Name: checked
Description: Whether the radio button is currently selected.
Type: boolean

disabled boolean

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean

readOnly boolean

Name: readOnly
Description: Whether the user should be unable to select the radio button.
Type: boolean

required boolean

Name: required
Description: Whether the user must choose a value before submitting a form.
Type: boolean

touched boolean

Name: touched
Description: Whether the field has been touched.
Type: boolean

dirty boolean

Name: dirty
Description: Whether the field value has changed from its initial value.
Type: boolean

valid boolean | null

Name: valid
Description: Whether the field is valid. null means validity is not known yet.
Type: boolean | null

filled boolean

Name: filled
Description: Whether the field has a value.
Type: boolean

focused boolean

Name: focused
Description: Whether the field is focused.
Type: boolean

data-checked

Present when the radio is checked.

data-unchecked

Present when the radio is not checked.

data-disabled

Present when the radio is disabled.

data-readonly

Present when the radio is readonly.

data-required

Present when the radio is required.

data-valid

Present when the radio is in a valid state (when wrapped in Field.Root).

data-invalid

Present when the radio is in an invalid state (when wrapped in Field.Root).

data-dirty

Present when the radio's value has changed (when wrapped in Field.Root).

data-touched

Present when the radio has been touched (when wrapped in Field.Root).

data-filled

Present when the radio is checked (when wrapped in Field.Root).

data-focused

Present when the radio is focused (when wrapped in Field.Root).

data-starting-style

Present when the radio indicator begins animating in.

data-ending-style

Present when the radio indicator is animating out.

Attribute	Description	-
`data-checked`	Present when the radio is checked.
`data-unchecked`	Present when the radio is not checked.
`data-disabled`	Present when the radio is disabled.
`data-readonly`	Present when the radio is readonly.
`data-required`	Present when the radio is required.
`data-valid`	Present when the radio is in a valid state (when wrapped in Field.Root).
`data-invalid`	Present when the radio is in an invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the radio's value has changed (when wrapped in Field.Root).
`data-touched`	Present when the radio has been touched (when wrapped in Field.Root).
`data-filled`	Present when the radio is checked (when wrapped in Field.Root).
`data-focused`	Present when the radio is focused (when wrapped in Field.Root).
`data-starting-style`	Present when the radio indicator begins animating in.
`data-ending-style`	Present when the radio indicator is animating out.