Radio Group

Storybook GitHub

<script setup lang="ts">
import { ref } from "vue";
import MtRadioGroupRoot from "@shopware-ag/meteor-component-library/MtRadioGroupRoot";
import MtRadioGroupList from "@shopware-ag/meteor-component-library/MtRadioGroupList";
import MtRadioGroupItem from "@shopware-ag/meteor-component-library/MtRadioGroupItem";

const selectedValue = ref("value1");
</script>

<template>
  <mt-radio-group-root v-model="selectedValue" label="Radio field">
    <mt-radio-group-list>
      <mt-radio-group-item id="option-1" value="value1" label="Option 1" />
      <mt-radio-group-item id="option-2" value="value2" label="Option 2" />
      <mt-radio-group-item id="option-3" value="value3" label="Option 3" />
    </mt-radio-group-list>
  </mt-radio-group-root>
</template>

Usage

Radio Group presents a set of mutually exclusive options where only one selection is allowed. Use it when the available choices should stay visible on the page instead of being hidden in a collapsed control, and when users benefit from scanning or comparing a small number of options before choosing one.

import {
  MtRadioGroupRoot,
  MtRadioGroupList,
  MtRadioGroupItem,
  MtRadioGroupCardItem,
  MtRadioGroupCustomItem,
  MtRadioGroupIndicator,
} from "@shopware-ag/meteor-component-library";

Examples

Card item

Use card items when each option needs a label and a short supporting description.

<script setup lang="ts">
import { ref } from "vue";
import {
  MtRadioGroupRoot,
  MtRadioGroupList,
  MtRadioGroupCardItem,
} from "@shopware-ag/meteor-component-library";

const selectedShippingMethod = ref("standard");
</script>

<template>
  <mt-radio-group-root v-model="selectedShippingMethod" label="Shipping method">
    <mt-radio-group-list>
      <mt-radio-group-card-item
        id="shipping-standard"
        value="standard"
        label="Standard delivery"
        description="Delivered within 3 to 5 business days."
      />
      <mt-radio-group-card-item
        id="shipping-express"
        value="express"
        label="Express delivery"
        description="Delivered on the next business day."
      />
    </mt-radio-group-list>
  </mt-radio-group-root>
</template>

Custom item

Build fully custom option cards when you need richer content or a different layout.

<script setup lang="ts">
import { ref } from "vue";
import MtRadioGroupRoot from "@shopware-ag/meteor-component-library/MtRadioGroupRoot";
import MtRadioGroupCustomItem from "@shopware-ag/meteor-component-library/MtRadioGroupCustomItem";
import MtRadioGroupIndicator from "@shopware-ag/meteor-component-library/MtRadioGroupIndicator";
import ExampleRadioOption from "@shopware-ag/meteor-component-library/ExampleRadioOption";

const selectedPlan = ref("pro");
</script>

<template>
  <mt-radio-group-root v-model="selectedPlan" label="Choose a plan">
    <template #default="{ disabled, identification }">
      <div style="display: flex; gap: var(--scale-size-24)">
        <mt-radio-group-custom-item value="pro">
          <example-radio-option
            :checked="selectedPlan === 'pro'"
            :disabled="disabled"
            title="Pro"
            feature1="100 image generations"
            feature2="Unlimited workflows"
            feature3="Advanced analytics"
            price="$10"
          >
            <template #indicator>
              <mt-radio-group-indicator
                id="indicator-1"
                :name="identification"
                value="pro"
                :checked="selectedPlan === 'pro'"
                :disabled="disabled"
              />
            </template>
          </example-radio-option>
        </mt-radio-group-custom-item>
        <mt-radio-group-custom-item value="plus">
          <example-radio-option
            :checked="selectedPlan === 'plus'"
            :disabled="disabled"
            title="Plus"
            feature1="300 image generations"
            feature2="Unlimited workflows"
            feature3="Advanced analytics"
            price="$15"
          >
            <template #indicator>
              <mt-radio-group-indicator
                id="indicator-2"
                :name="identification"
                value="plus"
                :checked="selectedPlan === 'plus'"
                :disabled="disabled"
              />
            </template>
          </example-radio-option>
        </mt-radio-group-custom-item>
      </div>
    </template>
  </mt-radio-group-root>
</template>

Anatomy

Radio Group is a compound component made up of several public exports:

MtRadioGroupRoot provides the shared label, help text, hint, error handling, and selected-value state.
MtRadioGroupList lays out a standard vertical list of radio items with the expected spacing.
MtRadioGroupItem renders the default radio option with a label.
MtRadioGroupCardItem renders a bordered option card with a label and an optional description.
MtRadioGroupCustomItem lets you build fully custom option cards while still participating in the shared radio-group state.
MtRadioGroupIndicator renders the actual radio input and control, and is mainly useful inside custom-item compositions.

API reference

Root

Props

Prop	Type	Default
`model-value`	`string \| number \| boolean \| null`	`null`
`disabled`	`false \| true`	`false`
`aria-described-by`	`string`	`undefined`
`label`	`string`	`""`
`help-text`	`string`	`""`
`name`	`string`	`undefined`
`error`	`{ detail: string; }`	`undefined`
`hint` Optional caption below the field. The `#hint` slot takes precedence when provided.	`string \| null`	`null`

Events

Event	Payload
`update:modelValue`	`[value: string \| number \| boolean \| null]`

Slots

Slot	Bindings
`hint`	`{}`
`default`	`{ disabled: boolean; identification: string; }`

Card item

Props

Prop	Type	Default
`id` * The id of the radio input; its label and description refer to it.	`string`
`value` * The value the group takes when this option is selected.	`string \| number \| boolean`
`label` * The visible name of the option, which also names its radio input.	`string`
`description` Supporting text below the label, announced as the description of the radio input.	`string`	`undefined`
`required` Marks the radio input as required.	`false \| true`	`false`
`aria-described-by` The ids of further elements that describe the option.	`string`	`undefined`
`error` Marks the option as invalid for assistive technology (`aria-invalid`). The error state of the group applies as well.	`false \| true`	`false`

Best practices

Use clear, concise labels for each option.
Use a descriptive group label that explains what the user is selecting.
Include help text or a hint when the selection needs additional context.
Use the error prop to display validation errors when needed.
Ensure each radio item has a unique id and value.
Use MtRadioGroupList to space standard items or card items vertically.
Use MtRadioGroupItem for simple choices that only need a label.
Use MtRadioGroupCardItem when a short description helps users compare options.
Use MtRadioGroupCustomItem for richer content or layouts, such as pricing plans with feature lists.
Keep the number of options manageable. A small visible set is the sweet spot.

Don't

Do not use Radio Group for multiple selections. Use Checkbox instead.
Do not use a single radio button. Radio groups should present a real choice.
Do not omit labels. Always provide clear labels for accessibility and usability.
Do not use radio groups for long lists of options where a Select would be easier to scan.
Do not use the same value for multiple items within the same group.
Do not forget to handle the v-model binding so the selected value stays in sync.

Behavior

Radio Group uses v-model on MtRadioGroupRoot to manage the selected value across all items in the group.
Use standard items and card items inside MtRadioGroupRoot. Both share the selected value, group name, and disabled state.
Clicking anywhere on a card selects its option. A disabled group prevents selection on all its cards.
Card items inherit the root's error state. Set a card's error prop to mark an individual option as invalid.
MtRadioGroupCustomItem gives you layout freedom, but you still need to render MtRadioGroupIndicator so the custom option remains a real radio control.
helpText, hint, and error follow the shared field patterns used by other form components.

Accessibility

Provide a clear group label or other nearby visible context so users understand what the choice controls.
MtRadioGroupIndicator uses native radio inputs. Tab enters or leaves the group, arrow keys move between options and select them, and Space selects the focused option.
Card items keep the native radio input and show a focus outline around the card during keyboard navigation.
A card's label names its radio input. Its description is associated with the input so screen readers can announce the supporting text.
Use ariaDescribedBy on a card to reference additional descriptive text by its element ID.
Keep option labels explicit so users do not need surrounding context to understand each choice.
If you build custom items, make sure the visible content still makes the selected state and choice meaning clear.

Checkbox: when users can turn an option on or off independently or choose multiple items.
Select: when there are more options or when space is limited.

Edit this pageorReport an issue

Promo Badge

A specialized Badge for predefined promotional labels such as New, Beta, or Shopware AI.

A lightweight input for filtering or finding content in a list, table, or page section.