Left Liquid Background
Right Liquid Background

Radio

A component for selecting a single option from a predefined set. Radio and RadioGroup provide a flexible foundation for building accessible, customizable choice interfaces in forms or filters.

Quick Links

Installation

Install the radio individually or as part of the complete @aristobyte-ui library.

Installation of Radio

The above command installs the Radio component individually. You may skip this step if @aristobyte-ui is already installed globally.

Package Manager

Individual Package

Install only the radio if you need specific functionality.

Full Library

Skip this if you have the complete @aristobyte-ui already installed.

Import

Choose between individual package imports or global library imports based on your project's needs and bundle size requirements.

Import Radio

You can either import Radio and RadioGroup directly from the package or rely on a global import setup. Both approaches ensure consistent and scoped styling.

Import Method

;

Individual Package

Import directly from the radio package for optimal tree-shaking and smaller bundle sizes.

Recommended for component-specific usage

Global Library

Import from the main library package when using multiple components from AristoByte UI.

Recommended for component-specific usage

Basic Usage Example

Basic implementation of the component using default properties. Suitable for general-purpose interactions.

Variants

The variant prop determines the visual styling of the radio control, allowing it to adapt to various semantic contexts or UI themes. Available values include default, primary, secondary, success, error, and warning. These variants typically map to predefined color tokens and help ensure design consistency across components. If not defined, the default style is applied. You may pass this prop to RadioGroup or to individual Radio components, where the latter will override inherited group values.

Preview

Guidelines

    Semantic Use

  • Use primary for key decision points.

  • Use default/neutral for low-stakes choices.

  • Use variants to visually group related options that map to different operational modes.

  • Avoid semantic variants for purely ornamental radios to prevent misuse by consumers.

    Design Notes

  • Keep variant consistent across a single group.

  • Ensure selected state contrast is unambiguous.

  • Provide a token map document for variant-to-token relationships for integrators.

  • Test variant rendering across brand themes to catch token overrides that reduce contrast.

Disabled

When the disabled prop is applied to the RadioGroup, it cascades to all nested Radio components, making them non-interactive. Even in a disabled state, radios can still reflect a checked value, preserving visual selection without allowing user interaction. You may also define disabled at the Radio level for more granular control—individual definitions take precedence.

Preview

Guidelines

    Operational Scenarios

  • Lock selection pending validation or permissions.

  • Prevent changes during in-flight submissions.

  • Use group-level disable to reflect read-only server side settings consistently.

  • Disable radios when subsequent steps depend on a confirmed upstream state.

    Developer Guidance

  • Explain disabled state via helper text.

  • Keep visual distinction clear from unchecked state.

  • Provide ARIA roles and descriptions to clarify disabled semantics for assistive tech.

  • Document how overrides behave when both group and individual radios are marked disabled.

Sizes

The size prop defines the scale of the radio control and its label. Available options include xsm, sm, md, lg, and xlg, giving developers flexibility to match component sizing with typography, spacing, and layout needs. The default size is md. This prop can be defined on both RadioGroup and Radio, with the latter taking priority when both are present.

Preview

Guidelines

    Layout Guidance

  • Use small for dense filters; large for touch-first UIs.

  • Scale with type ramp to maintain rhythm.

  • Prefer nominal sizes that map to global type-scale tokens for predictable layout.

  • Avoid using extremes simultaneously in the same form to prevent visual dissonance.

    Best Practices

  • Ensure labels remain readable at smaller sizes.

  • Maintain a11y hit area even when visually compact.

  • Document how size interacts with label wrapping and alignment in responsive contexts.

  • Include unit tests to assert the hit-target minimum dimensions across sizes.

Appearance

The appearance prop defines the visual structure of the radio's outline and its interaction state feedback. Available values include solid, outline, outline-dashed, no-outline, and glowing. By default, the radio adopts the outline appearance. Each variant provides a distinct visual tone—ranging from minimalist (no-outline) to expressive (glowing)—allowing precise alignment with your product's design language. This prop is supported on both RadioGroup and Radio; however, direct Radio definitions take precedence.

Preview

Guidelines

    When to Apply

  • Use outline for most enterprise use cases.

  • Use solid for high-emphasis, limited option sets.

  • Reserve glowing appearance for focused callouts or onboarding flows.

  • Choose no-outline when embedding radios into fully illustrated or branded surfaces.

    Design Best Practices

  • Avoid glowing in dense data surfaces.

  • Ensure dashed outlines remain visible at small sizes.

  • Document visual hierarchy for appearance options to help consumers choose appropriately.

  • Ensure appearance options have consistent hover/focus interactions to avoid surprises.

Highlight Label

Enables the label to inherit the active variant color when highlightLabel is set to true. This enhances visual association between the label and the selected theme. When false (default), the label color remains neutral or white. The prop can be used on RadioGroup to apply it broadly, but Radio-level values override group-level settings.

Preview

Guidelines

    When to Use

  • Use to emphasize selected options in short lists.

  • Avoid in long lists to reduce visual noise.

  • Use highlightLabel for compact decision UIs where color reinforces selection.

  • Avoid highlightLabel in dense dashboards where color overload reduces scanability.

    Design Notes

  • Maintain accessible color contrast on labels.

  • Ensure highlight doesn't imply clickability when disabled.

  • Provide option to programmatically toggle highlight for testing visual regressions.

  • Document highlight behavior for both group and individual radio overrides.

Align Radios

The align prop controls the directional layout of the Radio components within the RadioGroup. By default, radios are stacked vertical, but you can switch to a horizontal layout for more compact or inline presentations. Alignment can also be defined per Radio component, which overrides the group alignment if both are defined.

Preview

Guidelines

    Layout Patterns

  • Horizontal for up to 3-4 short options.

  • Vertical for long labels or many options.

  • When horizontal wrapping occurs, ensure each radio remains a separate focus target.

  • Prefer vertical stacking for accessibility when option labels are long or contain explanatory copy.

    Best Practices

  • Maintain consistent spacing between items.

  • Wrap long labels; don't shrink tap targets.

  • Provide responsive examples in docs to show how alignment adapts across breakpoints.

  • Consider alignment interactions with flex/grid containers to prevent overflow.

Align Label

The alignLabel prop allows fine-tuned control over the label's position relative to the radio control. It accepts top, right, bottom, or left, with bottom being the default. This prop can be applied to both Radio and RadioGroup, but individual Radio components take precedence when both are defined.

Preview

Guidelines

    Layout Guidance

  • Left/right for compact, inline content.

  • Top/bottom for forms with stacked fields.

  • Use top alignment for prominent labels that should read before the control.

  • Use left/right alignment for multi-column forms to save vertical space.

    Developer Notes

  • Ensure label remains clickable with the control.

  • Keep alignment consistent across a group.

  • Account for different languages and label lengths when choosing alignment to avoid overflow.

  • Provide a11y examples showing label association across alignment permutations.

Controlled Radios

A controlled RadioGroup allows full external control over the selected value using React state. By passing a dynamic value and onChange handler—typically derived from useState—you ensure the radio selection is synchronized with the component's state lifecycle. This pattern is ideal for form integrations, live previews, and data-bound interfaces where UI must reflect application state in real time.

Preview

Guidelines

    Integration Patterns

  • Sync with form libs (e.g., RHF, Formik).

  • Persist selected value to URL or store as needed.

  • Use controlled pattern to coordinate dependent form fields and derived state.

  • Avoid mixing uncontrolled radios in a controlled group to prevent unpredictable behavior.

    Implementation Notes

  • Treat value as immutable; update via onChange only.

  • Keep controlled and uncontrolled patterns separate.

  • Provide clear example code snippets for controlled/uncontrolled patterns in docs.

  • Debounce heavy updates triggered by radio changes to avoid thrashing connected systems.

Props Reference

Complete reference for all props available on Radio, RadioGroup component(s), including type definitions, default values, and usage examples.

  • Radio

    • Core Props

      • children

        React.ReactNode

      • value

        string

      • checked

        boolean

      • onChange

        (value: string) => void

      • name

        string

    • Visual Props

      • size

        'xsm' | 'sm' | 'md' | 'lg' | 'xlg'default: 'md'

      • variant

        'default' | 'primary' | 'secondary' | 'success' | 'error' | 'warning'default: 'default'

      • appearance

        'default' | 'solid' | 'outline' | 'outline-dashed' | 'no-outline' | 'glowing'default: 'default'

      • alignLabel

        'top' | 'right' | 'bottom' | 'left'default: 'right'

      • highlightLabel

        booleandefault: false

    • State Props

      • disabled

        booleandefault: false

    • Advanced Props

      • className

        stringdefault: ''

      • style

        React.CSSPropertiesdefault: {}

  • RadioGroup

    • Core Props

      • name

        string

      • value

        string

      • children

        React.ReactElement<IRadio> | React.ReactElement<IRadio>[]

      • onChange

        (newValue: string) => void

    • Visual Props

      • size

        'xsm' | 'sm' | 'md' | 'lg' | 'xlg'default: 'md'

      • variant

        'default' | 'primary' | 'secondary' | 'success' | 'error' | 'warning'default: 'default'

      • appearance

        'solid' | 'outline' | 'outline-dashed' | 'no-outline' | 'glowing'default: 'outline'

      • align

        'horizontal' | 'vertical'default: 'horizontal'

      • alignLabel

        'top' | 'right' | 'bottom' | 'left'default: 'right'

      • highlightLabel

        booleandefault: false

    • State Props

      • disabled

        booleandefault: false

    • Advanced Props

      • className

        stringdefault: ''

      • style

        React.CSSPropertiesdefault: {}

Viewing Unit with ID radio