Radio Group

Source

<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,
  MtRadioGroupCustomItem,
  MtRadioGroupIndicator,
} from "@shopware-ag/meteor-component-library";

Examples

Custom item

Build fully custom option cards while keeping the shared radio-group state.

<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.
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

Props

Prop	Type	Default
`model-value`	`string \| number \| boolean \| null`	`null`
`disabled`	`boolean`	`false`
`aria-described-by`	`string`	`undefined`
`label`	`string`	`""`
`help-text`	`string`	`""`
`name`	`string`	`undefined`
`error`	`{ detail: string; }`	`undefined`

Events

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

Slots

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

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 wrap multiple MtRadioGroupItem components for proper spacing.
Use MtRadioGroupCustomItem when you need custom-styled radio options such as pricing plans or feature cards.
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.
MtRadioGroupItem should always be used inside MtRadioGroupRoot, because it depends on the shared radio-group context.
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, so the group benefits from standard browser keyboard behavior.
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.