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.
Custom item
Build fully custom option cards when you need richer content or a different layout.
Disabled option
Disable a single option when it is not available, and use the group's hint to explain why.
Anatomy
Radio Group is a compound component made up of several public exports:
MtRadioGroupRootprovides the shared label, help text, hint, error handling, and selected-value state.MtRadioGroupListlays out a standard vertical list of radio items with the expected spacing.MtRadioGroupItemrenders the default radio option with a label.MtRadioGroupCardItemrenders a bordered option card with a label and an optional description.MtRadioGroupCustomItemlets you build fully custom option cards while still participating in the shared radio-group state.MtRadioGroupIndicatorrenders the actual radio input and control, and is mainly useful inside custom-item compositions.
API reference
MtRadioGroupRoot
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 |
hintOptional 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; } |
MtRadioGroupList
Slots
| Slot | Bindings |
|---|---|
default | {} |
MtRadioGroupItem
Props
| Prop | Type | Default |
|---|---|---|
id * | string | |
value * | string | number | boolean | |
label * | string | |
disabledDisables this option. The option is also disabled when the whole group is disabled. | false | true | false |
required | false | true | false |
aria-described-by | string | undefined |
error | false | true | false |
MtRadioGroupCardItem
Props
| Prop | Type | Default |
|---|---|---|
id * | string | |
value * | string | number | boolean | |
label * | string | |
description | string | undefined |
disabledDisables this card. The card is also disabled when the whole group is disabled. | false | true | false |
required | false | true | false |
aria-described-by | string | undefined |
error | false | true | false |
MtRadioGroupCustomItem
Props
| Prop | Type | Default |
|---|---|---|
value * | string | number | boolean | |
disabledDisables this option, including the `MtRadioGroupIndicator` inside it. The option is also
disabled when the whole group is disabled. | false | true | false |
Slots
| Slot | Bindings |
|---|---|
default | { disabled: boolean; } |
MtRadioGroupIndicator
Props
| Prop | Type | Default |
|---|---|---|
id * | string | |
name * | string | |
value * | string | number | boolean | |
checked * | false | true | |
disabledDisables the radio input. Inside a disabled `MtRadioGroupCustomItem`, the input is disabled
even without this prop. | false | true | false |
required | false | true | false |
aria-described-by | string | undefined |
error | false | true | false |
Best practices
Do
- 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
errorprop to display validation errors when needed. - Ensure each radio item has a unique
idandvalue. - Use
MtRadioGroupListto space standard items or card items vertically. - Use
MtRadioGroupItemfor simple choices that only need a label. - Use
MtRadioGroupCardItemwhen a short description helps users compare options. - Use
MtRadioGroupCustomItemfor richer content or layouts, such as pricing plans with feature lists. - Explain why an option is disabled, for example in the group's
hint. - 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
valuefor multiple items within the same group. - Do not forget to handle the
v-modelbinding so the selected value stays in sync.
Behavior
- Radio Group uses
v-modelonMtRadioGroupRootto 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.
- Set
disabledon an item, card item, or custom item to disable only that option. An option is disabled when either the option or the whole group is disabled. A disabled option that is already selected stays selected. - Card items inherit the root's error state. Set a card's
errorprop to mark an individual option as invalid. MtRadioGroupCustomItemgives you layout freedom, but you still need to renderMtRadioGroupIndicatorso the custom option remains a real radio control. Clicking the custom content selects the option, while links, buttons, and form controls inside it keep their own behavior.- The
MtRadioGroupIndicatorinside a custom item follows the item's disabled state. The item also passes that state to its slot asdisabled, so you can style the custom content. helpText,hint, anderrorfollow 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.
- The root's
labelnames the radio group for screen readers. The root'shintanderror, and any element referenced by itsariaDescribedBy, describe the group. MtRadioGroupIndicatoruses native radio inputs. Tab enters or leaves the group, arrow keys move between options and select them, and Space selects the focused option. Arrow keys skip disabled options.- 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
ariaDescribedByon 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.