Radio button - SKY UX design system

Modern visual theme

Radio buttons let users select one item from a short list of items.

Radio button group demo

Icon radio button group demo

Usage

Use when

Use radio button groups when users must choose one option from a set of 2-5. Use radio buttons in modals where users confirm decisions before changes take effect.

undefined — Do use radio button groups when users select a single item from a short list of options in a modal.

Use icon radio button groups when icons clearly communicate the options.

Use radio buttons to enable conditional inputs. For options that enable 1-3 inputs, disable the inputs until users select the radio buttons. For options that enable more inputs, hide the inputs until users select the radio buttons. If all options in a radio button group enable conditional inputs or significantly change the workflow, consider using action buttons instead. See the form layout guidelines for more information.

Don't use when

Don't use radio buttons when users must choose from more than five items. Use a different selection input instead.

Don't use radio buttons for two options that are exact opposites. Use a checkbox instead.

Don't use radio buttons when user selections significantly alter the workflow. Use action buttons instead, and place them at the beginning of the task.

Anatomy

Individual radio button

Radio button

Label

Help inline button (optional)

Hint text (optional)

Radio button group

Label

Radio buttons

Required field marker (optional)

Help inline button (optional)

Hint text (optional)

Icon radio button group

Icon radio button

Icon

Options

Headings

By default, the labels for radio button groups aren't treated as HTML headings. To emphasize a label as an HTML heading in a form hierarchy, you can use headingLevel to specify a semantic heading level in the document structure and headingStyle to set the heading font style. For example, use a label as a heading to indicate that a radio button group is a form section just like other field groups. Or use a label as a heading to emphasize a radio button group as the main section of a form, such as a test or a survey.

In rare cases, you can hide radio button group label text and use other text to present the radio buttons.

Required field marker

In rare cases, you can make a radio button group required and leave every option unselected to force users to select an option. When a radio button group is required, a red asterisk appears to the right of the radio group label. It includes the appropriate ARIA attributes to support users of assistive technologies. For more information about required fields, see the form design guidelines.

You can't make individual radio buttons required.

Help inline button

When you need to supplement a radio button or radio button group label with additional information but don't require persistent inline help, you can place a help inline button beside the label to invoke contextual user assistance.

Hint text

To highlight important considerations about a radio button or radio button group, use hint text. This persistent inline help can explain details such as:

Consequences of a choice that may not be apparent
Additional instructions or context, such as how data is used

Stacked margin

Radio button groups automatically add vertical spacing between individual radio buttons. For consistent vertical spacing when a radio button group is immediately followed by another form input, use stacked to add a bottom margin that visually separates the radio button group from the form input under it. For more information about spacing on forms, see the form layout guidelines.

Don't use stacked when the radio button group:

Is the last input inside a field group
Is the last input on a form

If a radio button group uses headingLevel, use stacked when the radio button group is followed by a field group or another heading. The radio button group automatically increases the size of the margin to fit the visual hierarchy.

Content

Make radio button group labels succinct and descriptive. In most cases, use nouns or noun phrases. When necessary, radio button group labels can use short sentences or sentence fragments.

For details about styling radio button group labels as headings, see the "Headings" section above.

Similarly, make radio button labels succinct and descriptive. But when necessary, radio button labels can use short sentences or sentence fragments.

Icon radio buttons use the icon component. For a list of common icons, see the SKY UX icon inventory. Don't display heading text or label text on icon radio button groups.

Layout

Don't wrap a radio button group inside a field group component if the radio button group is the only content.

In this example, “Payment processing mode” should be the heading of the radio button group, with headingLevel and headingStyle set to 3 in the component options. An additional field group and label around the radio button group is unnecessary and confusing.

Accessibility

Radio button groups will automatically create <fieldset>and <legend> elements from their contents and heading text.

In most cases, radio button group labels are not treated as semantic h elements, but when necessary, you can specify a heading level and heading style. For example, when a lone radio button group appears on a form field with field groups, set the radio button group's headingLevel to 3 and headingStyle to sky-font-heading-3 to match the semantic and visual hierarchy of field group headings.

Components

Guidelines

Form design

Installation

Defined in: SkyRadioModule None found.
NPM package: @skyux/formsView in NPM | View in GitHub None found.
Installation: npm install --save-exact @skyux/forms
None found.

Components

SkyRadioGroupComponent

Organizes radio buttons into a group. It is required for radio buttons on Angular reactive forms, and we recommend using it with all radio buttons. On Angular forms, the component manages the selected values and keeps the forms up-to-date. When users select a radio button, its value is driven through an ngModel attribute that you specify on the sky-radio-group element.

Selector

sky-radio-group

Input	Description
`name: string`	Danger: Required. The name for the collection of radio buttons that the component groups together. This property overwrites the deprecated `name` property on individual `sky-radio` elements, and it is required unless the `name` property is set on individual `sky-radio` elements.
`ariaLabel?: string`	Deprecated. Use `headingText` instead. The ARIA label for the radio button group. This sets the radio button group's `aria-label` attribute to provide a text equivalent for screen readers to support accessibility. If the radio button group includes a visible label, use `ariaLabelledBy` instead. For more information about the `aria-label` attribute, see the WAI-ARIA definition. Optional.
`ariaLabelledBy?: string`	Deprecated. Use `headingText` instead. The HTML element ID of the element that labels the radio button group. This sets the radio button group's `aria-labelledby` attribute to provide a text equivalent for screen readers to support accessibility. If the radio button group does not include a visible label, use `ariaLabel` instead. For more information about the `aria-labelledby` attribute, see the WAI-ARIA definition. Optional.
`disabled?: boolean`	Whether to disable the input on template-driven forms. Don't use this input on reactive forms because they may overwrite the input or leave the control out of sync. To set the disabled state on reactive forms, use the `FormControl` instead. Optional. Default is `false`.
`headingHidden?: boolean`	Indicates whether to hide the `headingText`. Optional. Default is `false`.
`headingLevel?: SkyRadioGroupHeadingLevel`	The semantic heading level in the document structure. By default, the heading text is not wrapped in a heading element. Optional.
`headingStyle?: SkyRadioGroupHeadingStyle`	The heading font style. Optional. Default is `4`.
`headingText?: string`	The text to display as the radio group's heading. Optional.
`helpKey?: string`	A help key that identifies the global help content to display. When specified, a help inline button is placed beside the radio group heading. Clicking the button invokes global help as configured by the application. This property only applies when `headingText` is also specified. Optional.
`helpPopoverContent?: string \| TemplateRef<unknown>`	The content of the help popover. When specified along with `headingText`, a help inline button is added to radio group. The help inline button displays a popover when clicked using the specified content and optional title. This property only applies when `headingText` is also specified. Optional.
`helpPopoverTitle?: string`	The title of the help popover. This property only applies when `helpPopoverContent` is also specified. Optional.
`hintText?: string`	Persistent inline help text that provides additional context to the user. Optional.
`required?: boolean`	Whether the input is required for form validation. When you set this property to `true`, the component adds `aria-required` and `required` attributes to the input element so that forms display an invalid state until the input element is complete. For more information about the `aria-required` attribute, see the WAI-ARIA definition. Optional. Default is `false`.
`stacked?: boolean`	Whether the radio button group is stacked on another form component. When specified, the appropriate vertical spacing is automatically added to the radio button group. Optional.
`tabIndex?: number`	The index for all the radio buttons in the group. If the index is not defined, the indices for individual radio buttons are set to their positions on load. This property supports accessibility by placing focus on the currently selected radio button. If no radio button is selected, it places focus on the first or last button depending on how users navigate to the radio button group. Optional.
`value?: any`	The value of the radio button to select by default when the group loads. The value corresponds to the `value` property of an individual `sky-radio` element within the group. Optional.

SkyRadioLabelComponent

Specifies a label for the radio button. To display a help button beside the label, include a help button element, such as sky-help-inline, in the sky-radio-label element and a sky-control-help CSS class on that help button element.

Selector

sky-radio-label

SkyRadioComponent

Renders a SKY UX-themed replacement for an HTML input element with type="radio". When users select a radio button, its value is driven through an ngModel attribute that you specify on the sky-radio element or the parent sky-radio-group element.

Selector

sky-radio

Input	Description
`value: any`	Danger: Required. The value bound to the radio button's `value` property. The value usually corresponds to the radio button's label, which you specify with the `sky-radio-label` component.
`checked?: boolean`	Whether the radio button is selected. Optional. Default is `false`.
`disabled?: boolean`	Whether to disable the input on template-driven forms. Don't use this input on reactive forms because they may overwrite the input or leave the control out of sync. To set the disabled state on reactive forms, use the `FormControl` instead. Optional. Default is `false`.
`helpKey?: string`	A help key that identifies the global help content to display. When specified, a help inline button is placed beside the radio button label. Clicking the button invokes global help as configured by the application. This property only applies when `labelText` is also specified. Optional.
`helpPopoverContent?: string \| TemplateRef<unknown>`	The content of the help popover. When specified along with `labelText`, a help inline button is added to radio button. The help inline button displays a popover when clicked using the specified content and optional title. This property only applies when `labelText` is also specified. Optional.
`helpPopoverTitle?: string`	The title of the help popover. This property only applies when `helpPopoverContent` is also specified. Optional.
`hintText?: string`	Persistent inline help text that provides additional context to the user. Optional.
`icon?: string`	The icon to display in place of the radio button. To group radio buttons like in the demo above, place the `sky-switch-icon-group` class on the direct parent element of the radio buttons. Optional.
`id?: string`	The ID for the radio button. If a value is not provided, an autogenerated ID is used. Optional.
`label?: string`	Deprecated. Use `labelText` instead. The ARIA label for the radio button. This sets the radio button's `aria-label` attribute to provide a text equivalent for screen readers to support accessibility when the radio button does not include a visible label. You must set this property for icon radio buttons. If the radio button includes a visible label, use `labelledBy` instead. For more information about the `aria-label` attribute, see the WAI-ARIA definition. Optional.
`labelHidden?: boolean`	Indicates whether to hide the `labelText`. Optional. Default is `false`.
`labelText?: string`	The text to display as the radio button's label. Use this instead of the `sky-radio-label` when the label is text-only. Optional.
`labelledBy?: string`	Deprecated. Use `labelText` instead. The HTML element ID of the element that labels the radio button. This sets the radio button's `aria-labelledby` attribute to provide a text equivalent for screen readers to support accessibility. If the radio button does not include a visible label, use `label` instead. For more information about the `aria-labelledby` attribute, see the WAI-ARIA definition. Optional.
`name?: string`	Deprecated. This property is deprecated in favor of the `name` property on the `sky-radio-group element`. We recommend using the `sky-radio-group` element with all radio buttons, but if you opt not to, then this property specifies a name for a group of radio buttons. Optional.
`radioType?: SkyRadioType`	Deprecated. radioType is no longer supported The background color type after users select an icon radio button. The valid options correspond the label component's label types. `danger` creates a red background, `info` creates a blue background, `success` creates a green background, and `warning` creates an orange background. Optional. Default is `"info"`.
`tabindex?: number`	Deprecated. This property is deprecated in favor of the `tabIndex` property on the `sky-radio-group` element. It specifies an index for the radio button. If the index is not defined, it is set to the position of the radio button on load. Optional.

Event	Description
`change: EventEmitter<SkyRadioChange>`	Fires when users select a radio button.
`checkedChange: EventEmitter<boolean>`	Fires when the selected value changes.
`disabledChange: EventEmitter<boolean>`	Fires when the selected value changes.

SkyFormErrorComponent

Displays default and custom form field error messages for form field components. Set labelText on the form field component to automatically display required, maximum length, minimum length, date, email, phone number, time, and URL errors. To display custom errors, include sky-form-error elements in the form field component.

Selector

sky-form-error

Input	Description
`errorName: string`	Danger: Required. The name of the error.
`errorText: string`	Danger: Required. The error message to display.

Interfaces

SkyRadioChange

Fires when users select a radio button.

interface SkyRadioChange {
  value: any;
}

Property	Description
`value: any`	The value from the radio component.

Type aliases

SkyRadioGroupHeadingLevel

type SkyRadioGroupHeadingLevel = 3 | 4 | 5

SkyRadioGroupHeadingStyle

type SkyRadioGroupHeadingStyle = 3 | 4 | 5

SkyRadioType

type SkyRadioType = 'danger' | 'info' | 'success' | 'warning'

Standard radio buttons

demo.component.ts

demo.component.html

Markup

<div class="sky-padding-even-lg">
  <form [formGroup]="formGroup">
    <sky-radio-group
      formControlName="paymentMethod"
      headingLevel="4"
      headingText="Payment method"
      [helpPopoverContent]="helpPopoverContent"
      [helpPopoverTitle]="helpPopoverTitle"
      [hintText]="hintText"
    >
      <ul class="sky-list-unstyled">
        <li *ngFor="let option of paymentOptions">
          <sky-radio
            [disabled]="option.disabled"
            [value]="option.value"
            [labelText]="option.name"
            [helpPopoverContent]="option.helpContent"
            [hintText]="option.hintText"
          />
        </li>
      </ul>
      <sky-form-error
        *ngIf="paymentMethod.errors?.['processingIssue']"
        errorName="processingIssue"
        errorText="An error occurred with this payment method. Please contact us to resolve."
      />
    </sky-radio-group>
  </form>
</div>

TypeScript

import { CommonModule } from '@angular/common';
import { Component, inject } from '@angular/core';
import {
  AbstractControl,
  FormBuilder,
  FormControl,
  FormGroup,
  FormsModule,
  ReactiveFormsModule,
  ValidationErrors,
} from '@angular/forms';
import { SkyRadioModule } from '@skyux/forms';

interface DemoForm {
  paymentMethod: FormControl<string | null>;
}

interface Item {
  name: string;
  value: string;
  disabled?: boolean;
  hintText?: string;
  helpContent?: string;
}

function validatePaymentMethod(
  control: AbstractControl,
): ValidationErrors | null {
  return control.value === 'check' ? { processingIssue: true } : null;
}

@Component({
  standalone: true,
  selector: 'app-demo',
  templateUrl: './demo.component.html',
  imports: [CommonModule, FormsModule, ReactiveFormsModule, SkyRadioModule],
})
export class DemoComponent {
  protected formGroup: FormGroup<DemoForm>;
  protected helpPopoverContent =
    "We don't charge fees for any payment method. The only exception is when credit card payments are late, which incurs a 2% fee.";
  protected helpPopoverTitle = 'Are there fees?';
  protected hintText = 'Card methods require proof of identification.';
  protected paymentMethod: FormControl<string | null>;

  protected paymentOptions: Item[] = [
    {
      name: 'Cash',
      value: 'cash',
      helpContent:
        'We accept cash at any of our locations and affiliated partners.',
    },
    { name: 'Check', value: 'check' },
    { name: 'Apple pay', value: 'apple', disabled: true },
    {
      name: 'Credit',
      value: 'credit',
      hintText: 'A 2% late fee is applied to payments made after the due date.',
    },
    { name: 'Debit', value: 'debit' },
  ];

  readonly #formBuilder = inject(FormBuilder);

  constructor() {
    this.paymentMethod = this.#formBuilder.control(
      this.paymentOptions[0].name,
      {
        validators: [validatePaymentMethod],
      },
    );

    this.formGroup = this.#formBuilder.group({
      paymentMethod: this.paymentMethod,
    });
  }
}

Icon radio group

demo.component.ts

demo.component.html

Markup

<div class="sky-padding-even-lg">
  <form [formGroup]="formGroup">
    <sky-radio-group
      class="sky-switch-icon-group"
      formControlName="myView"
      headingHidden="true"
      headingText="View"
    >
      <sky-radio
        *ngFor="let view of views"
        [icon]="view.icon"
        [labelHidden]="true"
        [labelText]="view.label"
        [value]="view.name"
      />
    </sky-radio-group>
  </form>
</div>

TypeScript

import { CommonModule } from '@angular/common';
import { Component, inject } from '@angular/core';
import {
  FormBuilder,
  FormGroup,
  FormsModule,
  ReactiveFormsModule,
} from '@angular/forms';
import { SkyRadioModule } from '@skyux/forms';

interface Item {
  icon: string;
  label: string;
  name: string;
}

@Component({
  standalone: true,
  selector: 'app-demo',
  templateUrl: './demo.component.html',
  imports: [CommonModule, FormsModule, ReactiveFormsModule, SkyRadioModule],
})
export class DemoComponent {
  protected formGroup: FormGroup;

  protected views: Item[] = [
    { icon: 'table', label: 'Table', name: 'table' },
    { icon: 'list', label: 'List', name: 'list' },
    { icon: 'map-marker', label: 'Map', name: 'map' },
  ];

  constructor() {
    this.formGroup = inject(FormBuilder).group({
      myView: this.views[0].name,
    });
  }
}