sp-radio

NPM 1.5.0

View Storybook

Try it on webcomponents.dev
Overview API Changelog

Overview

<sp-radio> and <sp-radio-group> allow users to select a single option from a list of mutually exclusive options. All possible options are exposed up front for users to compare.

Usage

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

yarn add @spectrum-web-components/radio

Import the side effectful registration of <sp-radio> or <sp-radio-group> via:

import '@spectrum-web-components/radio/sp-radio.js';
import '@spectrum-web-components/radio/sp-radio-group.js';

When looking to leverage the Radio or RadioGroup base classes as a type and/or for extension purposes, do so via:

import { Radio, RadioGroup } from '@spectrum-web-components/radio';

Anatomy

<sp-radio-group> holds a list of <sp-radio> elements, and is responsible for deselecting radio buttons when a new one is selected, which in turn makes it responsible for keeping track of which one is selected. <sp-radio> is responsible for handling user interactions and for visually reflecting if it is the one that is checked or not.

<sp-radio-group label="Choose an option" name="anatomy">
    <sp-radio value="first">Option 1</sp-radio>
    <sp-radio value="second">Option 2</sp-radio>
    <sp-radio value="third">Option 3</sp-radio>
    <sp-radio value="fourth">Option 4</sp-radio>
</sp-radio-group>

Label

The <sp-radio> elements are labelled with text in their default slot.

<sp-radio-group label="Choose an option" name="anatomy">
    <sp-radio value="first">Option 1</sp-radio>
    <sp-radio value="second">Option 2</sp-radio>
    <sp-radio value="third">Option 3</sp-radio>
    <sp-radio value="fourth">Option 4</sp-radio>
</sp-radio-group>

Options

Sizes

Small 
<sp-radio-group label="Small" selected="first" name="small">
    <sp-radio value="first" size="s">Option 1</sp-radio>
    <sp-radio value="second" size="s">Option 2</sp-radio>
    <sp-radio value="third" size="s">Option 3</sp-radio>
    <sp-radio value="fourth" size="s">Option 4</sp-radio>
</sp-radio-group>
 Medium 
<sp-radio-group label="Medium" selected="first" name="medium">
    <sp-radio value="first" size="m">Option 1</sp-radio>
    <sp-radio value="second" size="m">Option 2</sp-radio>
    <sp-radio value="third" size="m">Option 3</sp-radio>
    <sp-radio value="fourth" size="m">Option 4</sp-radio>
</sp-radio-group>
 Large 
<sp-radio-group label="Large" selected="first" name="large">
    <sp-radio value="first" size="l">Option 1</sp-radio>
    <sp-radio value="second" size="l">Option 2</sp-radio>
    <sp-radio value="third" size="l">Option 3</sp-radio>
    <sp-radio value="fourth" size="l">Option 4</sp-radio>
</sp-radio-group>
 Extra Large 
<sp-radio-group label="Extra large" selected="first" name="extra-large">
    <sp-radio value="first" size="xl">Option 1</sp-radio>
    <sp-radio value="second" size="xl">Option 2</sp-radio>
    <sp-radio value="third" size="xl">Option 3</sp-radio>
    <sp-radio value="fourth" size="xl">Option 4</sp-radio>
</sp-radio-group>

Styles

Standard radio buttons are the default style for radio buttons. They are optimal for application panels where all visual elements are monochrome in order to direct focus to the content.

Emphasized radio buttons are a secondary style for radio buttons. The blue color provides a visual prominence that is optimal for forms, settings, etc. where the radio buttons need to be noticed.

Standard 
<div style="display: flex; justify-content: space-between;">
    <div style="display: flex; flex-direction: column;">
        <sp-field-label for="example-1" size="l">
            <h4 class="spectrum-Heading--subtitle1">Default</h4>
        </sp-field-label>
        <sp-radio-group id="example-1" name="example" vertical>
            <sp-radio value="kittens">Kittens</sp-radio>
            <sp-radio value="puppies" checked>Puppies</sp-radio>
        </sp-radio-group>
    </div>

    <div style="display: flex; flex-direction: column;">
        <sp-field-label for="example-2" size="l">
            <h4 class="spectrum-Heading--subtitle1">Invalid</h4>
        </sp-field-label>
        <sp-radio-group invalid id="example-2" name="example" vertical>
            <sp-radio invalid value="kittens">Kittens</sp-radio>
            <sp-radio invalid value="puppies" checked>Puppies</sp-radio>
             <sp-help-text slot="negative-help-text" icon>
                This selection is invalid.
            </sp-help-text>
        </sp-radio-group>
    </div>

    <div style="display: flex; flex-direction: column;">
        <sp-field-label for="example-3" size="l">
            <h4 class="spectrum-Heading--subtitle1">Disabled</h4>
        </sp-fieldlabel>
        <sp-radio-group id="example-3" name="example" vertical>
            <sp-radio disabled value="kittens">Kittens</sp-radio>
            <sp-radio disabled value="puppies" checked>Puppies</sp-radio>
        </sp-radio-group>
    </div>
</div>
 Emphasized 
<div style="display: flex; justify-content: space-between;">
    <div style="display: flex; flex-direction: column;">
        <sp-field-label for="example-a" size="l">
            <h4 class="spectrum-Heading--subtitle1">Default</h4>
        </sp-field-label>
        <sp-radio-group id="example-a" name="example" vertical>
            <sp-radio emphasized value="kittens">Kittens</sp-radio>
            <sp-radio emphasized value="puppies" checked>Puppies</sp-radio>
        </sp-radio-group>
    </div>

    <div style="display: flex; flex-direction: column;">
        <sp-field-label for="example-b" size="l">
            <h4 class="spectrum-Heading--subtitle1">Invalid</h4>
        </sp-field-label>
        <sp-radio-group invalid id="example-b" name="example" vertical>
            <sp-radio emphasized invalid value="kittens">Kittens</sp-radio>
            <sp-radio emphasized invalid value="puppies" checked>Puppies</sp-radio>
            <sp-help-text slot="negative-help-text" icon>
                This selection is invalid.
            </sp-help-text>
        </sp-radio-group>
    </div>

    <div style="display: flex; flex-direction: column;">
        <sp-field-label for="example-c" size="l">
            <h4 class="spectrum-Heading--subtitle1">Disabled</h4>
        </sp-fieldlabel>
        <sp-radio-group id="example-c" name="example" vertical>
            <sp-radio emphasized disabled value="kittens">Kittens</sp-radio>
            <sp-radio emphasized disabled value="puppies" checked>Puppies</sp-radio>
        </sp-radio-group>
    </div>
</div>

Behaviors

Handling events

Event handlers for clicks and other user actions can be registered on an <sp-radio> similar to a standard <input type="radio"> element.

<sp-radio id="radio-example" onclick="spAlert(this, '<sp-radio> clicked!')">
    Web component
</sp-radio>

Accessibility

Tabbing into a group of radio buttons places the focus on the first radio button selected. If none of the radio buttons are selected, the focus is set on the first one in the group. Space selects the radio button in focus (if not already selected). Using the arrow keys moves focus and selection to the previous or next radio button in the group (last becomes first, and first becomes last). The new radio button in focus gets selected even if the previous one was not.

Provide a label

Radio groups and radio items should always have labels.

Attributes and Properties

Property Attribute Type Default Description checked checked boolean false Represents when the input is checked disabled disabled boolean false Uses the disabled style emphasized emphasized boolean false invalid invalid boolean false Uses the invalid style readonly readonly boolean false value value string '' Identifies this radio button within its radio group

Slots

Name Description default slot text label of the Radio button

Events

Name Type Description change Event When the input is interacted with and its state is changed

Patch Changes

  • Updated dependencies [165a904]:
    • @spectrum-web-components/help-text@1.5.0
    • @spectrum-web-components/field-group@1.5.0
    • @spectrum-web-components/base@1.5.0
    • @spectrum-web-components/reactive-controllers@1.5.0
    • @spectrum-web-components/shared@1.5.0

1.4.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/field-group@1.4.0
    • @spectrum-web-components/help-text@1.4.0
    • @spectrum-web-components/base@1.4.0
    • @spectrum-web-components/reactive-controllers@1.4.0
    • @spectrum-web-components/shared@1.4.0

1.3.0

Patch Changes

  • Updated dependencies [ea38ef0]:
    • @spectrum-web-components/reactive-controllers@1.3.0
    • @spectrum-web-components/field-group@1.3.0
    • @spectrum-web-components/help-text@1.3.0
    • @spectrum-web-components/base@1.3.0
    • @spectrum-web-components/shared@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.2.0 (2025-02-27)

Note: Version bump only for package @spectrum-web-components/radio

1.1.2 (2025-02-12)

Note: Version bump only for package @spectrum-web-components/radio

1.1.1 (2025-01-29)

Note: Version bump only for package @spectrum-web-components/radio

1.1.0 (2025-01-29)

Bug Fixes

  • lock prerelease versions for Spectrum CSS (#5014) (8aa7734)

1.0.3 (2024-12-09)

Note: Version bump only for package @spectrum-web-components/radio

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/radio

1.0.0 (2024-10-31)

Note: Version bump only for package @spectrum-web-components/radio

0.49.0 (2024-10-15)

Note: Version bump only for package @spectrum-web-components/radio

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/radio

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/radio

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/radio

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/radio

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/radio

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/radio

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/radio

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/radio

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/radio

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/radio

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/radio

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/radio

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/radio

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/radio

0.42.0 (2024-03-19)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/radio

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/radio

0.41.0 (2024-02-13)

Note: Version bump only for package @spectrum-web-components/radio

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/radio

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/radio

0.40.3 (2024-01-11)

Bug Fixes

  • button: adds pending button, fixes #3162 (#3163) (71254ec)

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/radio

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/radio

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/radio

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/radio

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/radio

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/radio

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/radio

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/radio

0.38.0 (2023-09-05)

Bug Fixes

  • radio-group: onChange event not triggering on keyboard navigation (#3592) (8501239)

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/radio

0.36.0 (2023-08-18)

Bug Fixes

  • radio: aria-disabled misspelling (b3fbd25), closes adobe/spectrum-web-components#3526

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/radio

0.34.0 (2023-07-11)

Bug Fixes

  • radio: fix radio documentation usage of sp-field-label[for] and sp-radio-group[id] (60f54fb)

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/radio

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/radio

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/radio

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/radio

0.30.0 (2023-05-03)

Bug Fixes

  • add support for "readonly" attribute (4bce3b7)
  • apply "HelpTextMixin" to form elements (a952447)
  • apply Focuable styles in class extensions (38f7afd)
  • complete deprecation of "quiet" attribute in checkbox and radio (29d8452)
  • correct @element jsDoc listing across library (c97a632)
  • correct a11y representation of a radio group (24ed0b8)
  • ensure [disabled] styling (4c067eb)
  • implement "emphasized" styles (750bbe7)
  • include "type" in package.json, generate custom-elements.json (1a8d716)
  • include default export in the "exports" fields (f32407d)
  • include the "types" entry in package.json files (b432f59)
  • lint away debugger statements (34a498e)
  • manage updated node types (0517fc1)
  • move hover/focus hoisting into conditioning (15ac2f7)
  • normalize "event" and "error" argument names (8d382cd)
  • prevent tabindex=-1 elements from placing focus on their host (1ac1293)
  • radio: ensure radio-group first selected value is followed (074bff8)
  • radio: process :focus and :focus-visible (77bc0e9)
  • radio: select in response to arrow keys not focus (b6acb59)
  • slider: use standard "change" and "input" events (59cf786)
  • stop merging selectors in a way that alters the cascade (369388f)
  • stop propagation of sp-radio "change" events at sp-radio-group boundary (f618460)
  • support matching keydown to [dir] (70b40a9)
  • update file path access (8898bf7)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • update side effect listings (8160d3a)
  • update to latest spectrum-css packages (a5ca19f)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • action-button: add action button pattern (03ac00a)
  • add t-shirt sizing to the Radio pattern (fc49343)
  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • field-group: add field-group pattern (f8d265c)
  • include all Dev Mode files in side effects (f70817c)
  • leverage "exports" field in package.json (321abd7)
  • overlay: manage focus throwing and tab trapping (27a0b53)
  • radio: update spectrum css input (4fef340)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • update lit-* dependencies, wip (377f3c8)
  • update to Spectrum CSS v3.0.0 (e8b3d8f)
  • use :focus-visable (via polyfill) instead of :focus (11c6fc7)
  • use @adobe/spectrum-css@2.15.1 (3918888)
  • use latest exports specification (a7ecf4b)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)
  • use imported TypeScript helpers instead of inlining them (cc2bd0a)

Reverts

  • Revert "chore: release new versions" (a6d655d)

0.11.14 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/radio

0.11.13 (2023-04-05)

Bug Fixes

  • radio: process :focus and :focus-visible (77bc0e9)

0.11.12 (2023-03-22)

Bug Fixes

  • move hover/focus hoisting into conditioning (15ac2f7)

0.11.11 (2023-03-08)

Note: Version bump only for package @spectrum-web-components/radio

0.11.10 (2023-02-08)

Note: Version bump only for package @spectrum-web-components/radio

0.11.9 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/radio

0.11.8 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/radio

0.11.7 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/radio

0.11.6 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/radio

0.11.5 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/radio

0.11.4 (2022-10-28)

Bug Fixes

  • manage updated node types (0517fc1)

0.11.3 (2022-10-17)

Note: Version bump only for package @spectrum-web-components/radio

0.11.2 (2022-10-10)

Note: Version bump only for package @spectrum-web-components/radio

0.11.1 (2022-09-14)

Note: Version bump only for package @spectrum-web-components/radio

0.11.0 (2022-08-24)

Features

  • add t-shirt sizing to the Radio pattern (fc49343)

0.10.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.9.15 (2022-08-04)

Note: Version bump only for package @spectrum-web-components/radio

0.9.14 (2022-07-18)

Note: Version bump only for package @spectrum-web-components/radio

0.9.13 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/radio

0.9.12 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/radio

0.9.11 (2022-05-27)

Note: Version bump only for package @spectrum-web-components/radio

0.9.10 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/radio

0.9.9 (2022-04-21)

Bug Fixes

  • stop propagation of sp-radio "change" events at sp-radio-group boundary (f618460)

0.9.8 (2022-03-30)

Note: Version bump only for package @spectrum-web-components/radio

0.9.7 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/radio

0.9.6 (2022-03-04)

Note: Version bump only for package @spectrum-web-components/radio

0.9.5 (2022-02-22)

Note: Version bump only for package @spectrum-web-components/radio

0.9.4 (2022-02-02)

Note: Version bump only for package @spectrum-web-components/radio

0.9.3 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/radio

0.9.2 (2022-01-07)

Note: Version bump only for package @spectrum-web-components/radio

0.9.1 (2021-12-13)

Bug Fixes

  • apply "HelpTextMixin" to form elements (a952447)

0.9.0 (2021-11-08)

Features

  • update lit-* dependencies, wip (377f3c8)

0.8.1 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/radio

0.8.0 (2021-11-02)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.7.14 (2021-10-12)

Note: Version bump only for package @spectrum-web-components/radio

0.7.13 (2021-09-20)

Note: Version bump only for package @spectrum-web-components/radio

0.7.12 (2021-09-13)

Note: Version bump only for package @spectrum-web-components/radio

0.7.11 (2021-08-24)

Bug Fixes

  • correct @element jsDoc listing across library (c97a632)

0.7.10 (2021-07-22)

Note: Version bump only for package @spectrum-web-components/radio

0.7.9 (2021-07-01)

Bug Fixes

  • correct a11y representation of a radio group (24ed0b8)

0.7.8 (2021-06-16)

Note: Version bump only for package @spectrum-web-components/radio

0.7.7 (2021-06-07)

Bug Fixes

  • lint away debugger statements (34a498e)

0.7.6 (2021-05-24)

Bug Fixes

  • prevent tabindex=-1 elements from placing focus on their host (1ac1293)

0.7.5 (2021-05-12)

Bug Fixes

  • radio: ensure radio-group first selected value is followed (074bff8)

0.7.4 (2021-04-09)

Note: Version bump only for package @spectrum-web-components/radio

0.7.3 (2021-03-29)

Note: Version bump only for package @spectrum-web-components/radio

0.7.2 (2021-03-22)

Bug Fixes

  • add support for "readonly" attribute (4bce3b7)

0.7.1 (2021-03-05)

Note: Version bump only for package @spectrum-web-components/radio

0.7.0 (2021-03-04)

Features

  • use latest exports specification (a7ecf4b)

0.6.3 (2021-02-11)

Bug Fixes

  • update to latest spectrum-css packages (a5ca19f)

0.6.2 (2021-02-02)

Note: Version bump only for package @spectrum-web-components/radio

0.6.1 (2021-01-28)

Note: Version bump only for package @spectrum-web-components/radio

0.6.0 (2021-01-21)

Bug Fixes

  • complete deprecation of "quiet" attribute in checkbox and radio (29d8452)
  • ensure [disabled] styling (4c067eb)
  • implement "emphasized" styles (750bbe7)
  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update file path access (8898bf7)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • action-button: add action button pattern (03ac00a)
  • field-group: add field-group pattern (f8d265c)
  • radio: update spectrum css input (4fef340)

0.5.0 (2021-01-13)

Bug Fixes

  • implement "emphasized" styles (750bbe7)
  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update file path access (8898bf7)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • action-button: add action button pattern (03ac00a)
  • field-group: add field-group pattern (f8d265c)
  • radio: update spectrum css input (4fef340)

0.4.4 (2020-10-12)

Note: Version bump only for package @spectrum-web-components/radio

0.4.3 (2020-10-12)

Bug Fixes

  • radio: select in response to arrow keys not focus (b6acb59)
  • include default export in the "exports" fields (f32407d)

0.4.2 (2020-09-25)

Bug Fixes

  • update side effect listings (8160d3a)

0.4.1 (2020-09-14)

Note: Version bump only for package @spectrum-web-components/radio

0.4.0 (2020-08-31)

Bug Fixes

  • support matching keydown to dir

Features

  • update to Spectrum CSS v3.0.0 (e8b3d8f)

0.3.3 (2020-08-19)

Note: Version bump only for package @spectrum-web-components/radio

0.3.2 (2020-07-27)

Note: Version bump only for package @spectrum-web-components/radio

0.3.1 (2020-07-22)

Note: Version bump only for package @spectrum-web-components/radio

0.3.0 (2020-07-17)

Features

  • overlay: manage focus throwing and tab trapping (27a0b53)
  • leverage "exports" field in package.json (321abd7)

0.2.12 (2020-06-08)

Note: Version bump only for package @spectrum-web-components/radio

0.2.11 (2020-04-16)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)

0.2.10 (2020-04-10)

Note: Version bump only for package @spectrum-web-components/radio

0.2.9 (2020-04-07)

Note: Version bump only for package @spectrum-web-components/radio

0.2.8 (2020-03-11)

Note: Version bump only for package @spectrum-web-components/radio

0.2.7 (2020-02-05)

Note: Version bump only for package @spectrum-web-components/radio

0.2.6 (2020-02-01)

Note: Version bump only for package @spectrum-web-components/radio

0.2.5 (2020-01-30)

Note: Version bump only for package @spectrum-web-components/radio

0.2.4 (2020-01-06)

Note: Version bump only for package @spectrum-web-components/radio

0.2.3 (2019-12-12)

Bug Fixes

  • apply Focuable styles in class extensions (38f7afd)

0.2.2 (2019-12-02)

Bug Fixes

  • normalize "event" and "error" argument names (8d382cd)

0.2.1 (2019-11-27)

Bug Fixes

  • include "type" in package.json, generate custom-elements.json (1a8d716)

0.2.0 (2019-11-19)

Features

  • use :focus-visable (via polyfill) instead of :focus (11c6fc7)
  • use @adobe/spectrum-css@2.15.1 (3918888)

0.1.5 (2019-11-01)

Bug Fixes

  • slider: use standard "change" and "input" events (59cf786)

0.1.4 (2019-10-14)

Performance Improvements

  • use imported TypeScript helpers instead of inlining them (cc2bd0a)

0.1.3 (2019-10-03)

Note: Version bump only for package @spectrum-web-components/radio