Skip to main content

RadioGroup

Choose one value from a visible set of radio options.

Props
Slots

Anatomy#

RadioGroup [component; slot=root]
└── item [slot]
    ├── container [slot]
    │   ├── input [internal]
    │   └── control [slot]
    │       └── indicator [slot]
    └── wrapper [slot]
        ├── label [slot]
        └── description [slot]

Usage#

Use RadioGroup for one choice from a small visible set. For a longer or space-constrained collection, use Select. Use CheckboxGroup when several options may be selected together.

import { Field, RadioGroup } from 'moraine'

export function Example() {
  return (
    <Field label="Visibility">
      <RadioGroup
        items={[
          { value: 'public', label: 'Public' },
          { value: 'private', label: 'Private' },
        ]}
      />
    </Field>
  )
}

Single selection#

items takes strings (used as both value and label) or objects with value, label, description, and disabled. The selected item is one string: use defaultValue for uncontrolled state, or pair value with onValueChange for controlled state. onValueChange fires only when the user selects a different item. Disabled items stay visible but cannot be selected or focused. variant sets the layout (list, card, or table), and orientation sets the direction.

<RadioGroup items={planOptions} value={plan()} onValueChange={setPlan} />

Keyboard interaction#

The group is one tab stop. The arrow keys that match orientation move focus to the next enabled item and select it. Home, End, and Shift with an arrow key move focus without selecting. Space selects the focused item. Navigation wraps unless loop={false}.

Forms#

Set name for native form submission. For schema binding and validation, place the group inside form.Field from createForm. Standalone Field supplies labels and messages without binding a form store.

<RadioGroup name="environment" items={envOptions} defaultValue="staging" />

Indicator#

indicatorPosition places the radio mark at the leading or trailing edge, or hides it with hidden.

<RadioGroup indicatorPosition="trailing" items={items} />
<RadioGroup indicatorPosition="hidden" items={items} />

Examples#

Choose a billing plan#

Keep one string value for the selected plan. Pair value with onValueChange when the page owns the choice.

import { RadioGroup } from 'moraine'
import type { RadioGroupT } from 'moraine'
import { createSignal } from 'solid-js'

const PLAN_OPTIONS = [
  { label: 'Free tier', value: 'free', description: 'For personal projects with basic features.' },
  {
    label: 'Pro tier',
    value: 'pro',
    description: 'Advanced collaboration and unlimited bandwidth.',
  },
  { label: 'Enterprise', value: 'enterprise', description: 'Dedicated support and custom SLA.' },
] satisfies RadioGroupT.Item[]

export function Selection() {
  const [plan, setPlan] = createSignal('pro')

  return (
    <div class="max-w-md w-full space-y-3">
      <RadioGroup items={PLAN_OPTIONS} value={plan()} onValueChange={setPlan} />
      <p class="text-xs text-muted-foreground">
        Active plan: <span class="text-foreground font-medium">{plan()}</span>
      </p>
    </div>
  )
}

Pick a plan with a locked starter tier#

Disable a legacy option so it stays visible but cannot be selected. Horizontal table layout works for a short plan comparison.

import { RadioGroup } from 'moraine'
import { createSignal } from 'solid-js'

export function ControlledDisabled() {
  const [value, setValue] = createSignal('pro')

  return (
    <div class="max-w-xl space-y-3">
      <RadioGroup
        items={[
          {
            value: 'starter',
            label: 'Starter (Legacy)',
            description: 'For personal projects',
            disabled: true,
          },
          { value: 'pro', label: 'Pro', description: 'For teams and scaling' },
          { value: 'enterprise', label: 'Enterprise', description: 'For regulated workloads' },
        ]}
        value={value()}
        onValueChange={setValue}
        variant="table"
        orientation="horizontal"
      />
      <p class="text-xs text-muted-foreground">Current plan: {value()}</p>
    </div>
  )
}

Bind a deployment environment#

Place the group in form.Field so schema validation owns the required environment value.

import { Button, createForm, RadioGroup } from 'moraine'
import type { RadioGroupT } from 'moraine'
import { createSignal } from 'solid-js'
import * as v from 'valibot'

const ENV_OPTIONS = [
  { label: 'Development', value: 'dev' },
  { label: 'Staging', value: 'staging' },
  { label: 'Production', value: 'prod' },
] satisfies RadioGroupT.Item[]

export function FormIntegration() {
  const [submittedEnv, setSubmittedEnv] = createSignal('staging')
  const form = createForm({
    schema: v.object({
      environment: v.pipe(v.string(), v.nonEmpty('Please select a target environment.')),
    }),
    initialInput: { environment: 'staging' },
    validate: 'input',
  })

  return (
    <form.Form onSubmit={(output) => setSubmittedEnv(output.environment)}>
      <div class="max-w-xl space-y-4">
        <form.Field
          name="environment"
          label="Target Deployment Environment"
          description="Determines runtime configuration and secrets applied."
          required
        >
          <RadioGroup items={ENV_OPTIONS} />
        </form.Field>
        <div class="flex gap-3 items-center">
          <Button type="submit" variant="soft" tone="neutral" size="sm">
            Validate
          </Button>
          <p class="text-xs text-muted-foreground">Target: {submittedEnv()}</p>
        </div>
      </div>
    </form.Form>
  )
}

Compare plans with the mark at the end#

indicatorPosition="trailing" puts the radio on the trailing edge of a card option. Use hidden when the card itself is the selected affordance.

import { RadioGroup } from 'moraine'

export function IndicatorPositions() {
  return (
    <div class="max-w-md w-full">
      <RadioGroup
        items={[
          { value: 'starter', label: 'Starter', description: 'For personal projects' },
          { value: 'pro', label: 'Pro', description: 'For teams and scaling' },
          { value: 'enterprise', label: 'Enterprise', description: 'For regulated workloads' },
        ]}
        variant="card"
        indicatorPosition="trailing"
        defaultValue="pro"
      />
    </div>
  )
}

API Reference#

Attributes#

Attributes
data-disabled
Slot: radio-groupradio-group-itemradio-group-control
Description: Present when the component, slot, or item is disabled.
data-invalid
Slot: radio-groupradio-group-control
Description: Present when the field or form has a validation error.
data-readonly
Slot: radio-groupradio-group-control
Description: Present when the field is in read-only mode.
data-required
Slot: radio-groupradio-group-control
Description: Present when the field input is required.
data-checked
Slot: radio-group-itemradio-group-controlradio-group-indicator
Description: Present when the item or toggle is checked.

Props#

Props for the RadioGroup component. Renders a <div> element by default.

Prop