Getting StartedComponentsDesign TokensThemingTheme SynthesizerFrameworksAccessibilityUtilitiesServer RenderingBrowser SupportContributingChangelogApp ShellAspect GridAuth ShellCenterContainerDashboard GridFloat BarInsetMasonryPage HeaderPage LayoutResizableResponsive SwitcherSectionSettings LayoutSplit PaneStatus BarStickyToolbarAnchor NavBottom NavBreadcrumbBreadcrumb MenuCommand BarDrawerFooterLinkMenubarNavigation MenuPage IndicatorPaginationRailScroll IndicatorScroll SpyScroll To TopSidebarSkip LinkStepper NavTabsTop BarTree ViewAccordionAspect RatioAvatarAvatar GroupCardCarouselCollapsibleColor SwatchCTA BannerDividerEmpty StateFeature CardIconImageImage CompareImage HotspotsInfinite ScrollLightboxMarqueeQR CodeScroll AreaSkeletonSpinnerStackVideoVirtual ListActivity HeatmapAnimated NumberBadgeBar ListChartClockComparisonCountdown TimerData GridDescription ListDiffGaugeJSON TreeKanbanLevel MeterListMeterSparklineStatStepperTagTimelineUptimeValue CardWaveformBlockquoteCode BlockCode GroupGradient TextHighlightKbdKeyboard MapMarkdownNumber FormatProseTerminalTextTime AgoTruncateTypewriterButtonButton GroupCalendarCheckboxChipColor PickerComboboxCopy ButtonDate PickerDate Range PickerField ListFieldsetFile UploadFormHotkeyIcon ButtonImage CropperInline EditInputInput GroupKnobLabelMasked InputMulti SelectNumber InputPassword InputPin InputRadio GroupRange SliderRatingSearchSegmented ControlSelectSignature PadSliderSortable ListSwitch GroupTag InputTextareaTheme ToggleTime PickerToggleTransfer ListTree SelectAlertAnnouncementBannerCommand PaletteConfirmConnection StatusContext MenuConversationDialogDropdown MenuHover CardLoading OverlayNotification PanelPopoverProgressSheetToastTooltip
ARC UIARC Radiant Components
v4.9DocsComponentsTokensSynthesizer
Getting StartedFrameworksServer RenderingDesign TokensThemingTheme SynthesizerTypographyUtilitiesAll ComponentsAccessibilityBrowser SupportChangelogContributingStatsApp ShellAspect GridAuth ShellCenterContainerDashboard GridFloat BarInsetMasonryPage HeaderPage LayoutResizableResponsive SwitcherSectionSettings LayoutSplit PaneStatus BarStickyToolbarAnchor NavBottom NavBreadcrumbBreadcrumb MenuCommand BarDrawerFooterLinkMenubarNavigation MenuPage IndicatorPaginationRailScroll IndicatorScroll SpyScroll To TopSidebarSkip LinkStepper NavTabsTop BarTree ViewAccordionAspect RatioAvatarAvatar GroupCardCarouselCollapsibleColor SwatchCTA BannerDividerEmpty StateFeature CardIconImageImage CompareImage HotspotsInfinite ScrollLightboxMarqueeQR CodeScroll AreaSkeletonSpinnerStackVideoVirtual ListActivity HeatmapAnimated NumberBadgeBar ListChartClockComparisonCountdown TimerData GridDescription ListDiffGaugeJSON TreeKanbanLevel MeterListMeterSparklineStatStepperTagTimelineUptimeValue CardWaveformBlockquoteCode BlockCode GroupGradient TextHighlightKbdKeyboard MapMarkdownNumber FormatProseTerminalTextTime AgoTruncateTypewriterButtonButton GroupCalendarCheckboxChipColor PickerComboboxCopy ButtonDate PickerDate Range PickerField ListFieldsetFile UploadFormHotkeyIcon ButtonImage CropperInline EditInputInput GroupKnobLabelMasked InputMulti SelectNumber InputPassword InputPin InputRadio GroupRange SliderRatingSearchSegmented ControlSelectSignature PadSliderSortable ListSwitch GroupTag InputTextareaTheme ToggleTime PickerToggleTransfer ListTree SelectAlertAnnouncementBannerCommand PaletteConfirmConnection StatusContext MenuConversationDialogDropdown MenuHover CardLoading OverlayNotification PanelPopoverProgressSheetToastTooltip

Radio Group

Single-select option group with arrow-key navigation and ARIA radiogroup semantics. Fits pricing tiers, settings panels, and any place where exactly one choice must be made from a visible set of options.

ComponentsRadio Group
inputhybrid
<arc-radio-group>

Overview

RadioGroup lets users pick exactly one option from a visible set. Unlike Select, which hides choices behind a dropdown, RadioGroup displays every option up front so users can compare them at a glance. This makes it the right choice when the number of options is small (typically two to six) and the decision benefits from side-by-side visibility: pricing tiers, shipping methods, account types, or preference toggles. The component manages focus with arrow-key navigation, following the WAI-ARIA radiogroup pattern. Pressing Arrow Down or Arrow Right moves focus to the next option and selects it; Arrow Up or Arrow Left moves backward. This roving-tabindex approach means the entire group occupies a single Tab stop, which keeps keyboard navigation fast. RadioGroup supports both vertical and horizontal orientations. Vertical is the default and works best for options with longer labels or descriptions. Horizontal layout suits compact rows of short labels, for example a row of size options (S, M, L, XL) or a light/dark theme toggle with more than two states. The component also submits with native forms through its `name` and `value` properties.

Guidelines

When to use

  • Use RadioGroup when users must choose exactly one option from two to six visible choices
  • Default-select the most common or recommended option to reduce decision friction
  • Use vertical orientation when option labels are longer than a few words
  • Pair with a visible label or heading so users understand what they are choosing
  • Group related radio groups under a shared fieldset or section heading

When not to use

  • Do not use RadioGroup for more than six or seven options; switch to Select or Combobox instead
  • Do not leave the group without a default selection unless the choice is truly optional
  • Do not mix RadioGroup with checkboxes in the same visual row: they imply different selection models
  • Do not use horizontal orientation with long labels: text will wrap awkwardly on small screens
  • Do not disable individual options without explaining why they are unavailable

Features

  • Single-select from a visible set of options: one choice at a time
  • Arrow-key navigation with roving tabindex (single Tab stop)
  • ARIA radiogroup role with automatic `aria-checked` management
  • Vertical and horizontal orientation modes
  • Disabled state for the entire group or individual options
  • Native form integration via name and value properties
  • Fires `arc-change` event on selection with the new value
  • Supports option objects with label and value fields

Preview

Starter — Free for individuals Pro — $12/mo for teams Enterprise — Custom pricing

Usage

Layout and styling work without JavaScript via the HTML/CSS versions. Interactive features like events and state management require the Web Component or a framework wrapper.

<script type="module" src="@arclux/arc-ui"></script>

<!-- Vertical (default) -->
<arc-radio-group name="plan" value="starter">
  <arc-radio value="starter">Starter — Free for individuals</arc-radio>
  <arc-radio value="pro">Pro — $12/mo for teams</arc-radio>
  <arc-radio value="enterprise">Enterprise — Custom pricing</arc-radio>
</arc-radio-group>

<!-- Horizontal layout -->
<arc-radio-group name="size" value="md" orientation="horizontal">
  <arc-radio value="sm">Small</arc-radio>
  <arc-radio value="md">Medium</arc-radio>
  <arc-radio value="lg">Large</arc-radio>
  <arc-radio value="xl">X-Large</arc-radio>
</arc-radio-group>

<script>
  document.querySelector('arc-radio-group')
    .addEventListener('arc-change', (e) => {
      console.log('Selected:', e.detail.value);
    });
</script>

API

valuestring''
The currently selected value. Must match one of the child arc-radio value attributes. Setting this property programmatically updates the visual selection and the internal aria-checked state.
namestring''
The form field name submitted with the selected value. Required for native form integration: without it, the selection will not appear in FormData.
disabledbooleanfalse
When true, disables all options in the group. The component becomes non-interactive: arrow-key navigation is suppressed, click events are ignored, and the group is excluded from the Tab order.
orientation'vertical' | 'horizontal''vertical'
Controls the layout direction of the radio options. Vertical stacks options top-to-bottom and maps Arrow Up/Down to navigation. Horizontal places options in a row and maps Arrow Left/Right.
size'sm' | 'md' | 'lg''md'
Controls the radio button and label size.
formAssociatedbooleantrue
propertiesobject{ // flag(), unlike `disabled`. The exclusion in props.js is specifically // about form-associated *platform* semantics: a `disabled` content // attribute that is merely present makes the element actually disabled // per the HTML spec, and formDisabledCallback assigns the property back, // so no converter can win. Neither of these is platform-mapped: // `required` is enforced by _computeValidity() below and `readonly` by // each component's own interaction handlers, so the stock converter buys // nothing here and costs the usual bug: `required="false"` read as true, // blocking submission of a form the author meant to leave optional. // Finding #48's shape, across all 26 form controls at once. required: flag(false), readonly: flag(false), }
Lit merges static properties up the prototype chain, so every consumer gets these without declaring them. required participates in constraint validation below; readonly reflects for styling and is enforced by each component's interaction handlers (the mixin can't know which gestures mutate state).
autoValidatesbooleantrue
Components that run their own constraint-validation logic (pattern checks, range checks) opt out of the automatic required sync by overriding this to false, and own the whole validity flag set instead.
form
validity
validationMessage
requiredbooleanfalse
readonlybooleanfalse

Methods

checkValidity()boolean
Whether the control currently satisfies its constraints, per the native constraint-validation API. Fires invalid on the element when it does not, and reports nothing to the user.
reportValidity()boolean
As checkValidity(), but also shows the browser's validation message against the control when it fails.

Events

arc-changedetail:{ value: string }
Fired when the selected radio value changes

Radio

<arc-radio>

Individual radio option rendered inside a RadioGroup. Each Radio represents a single selectable choice with its own label and value. Can be independently disabled while the rest of the group remains interactive.

label
valuestring''
The value submitted when this option is selected. Must be unique within the parent RadioGroup.
disabledbooleanfalse
When true, dims this individual option and removes it from keyboard navigation. The option cannot be selected by click or arrow keys.

See Also