Infragistics
Close
Angular React Web Components Blazor Web Components
Open Source

Radio Group

The Web Components Radio and Radio Group are components that let users select exactly one option from a set of mutually exclusive options. Each radio button represents one option, and the Radio Group arranges the radio buttons in a vertical or horizontal layout.

Live Demo

Anatomy

The Web Components Radio Group contains radio buttons, and each radio button is made of a radio control and a label.

Radio Group anatomy showing the label, the radio control, and the group of radio buttons
1. Radio Button Label: indicates the content you want to select or unselect
2. Radio Button: indicates if the state is selected. The default state of the input is unselected
3. Button Group: a container that groups related options and allows only one selection at a time

The following diagram shows the element structure of the Web Components Radio Group. Each radio button pairs its radio control with label content, which can be placed before or after the control.

igc-radio-group                  — groups the radio buttons
└── igc-radio                    — one per option
    └── [part="base"]            — the <label> that wraps the input, the control, and the label
        ├── input[type="radio"]  — the native radio input
        ├── [part="control"]     — the radio control
        └── [part="label"]       — the slotted label content

Getting Started

To use the Web Components Radio and Radio Group, follow the Ignite UI for Web Components Getting Started topic for the basic project setup, then import or register the components for your target platform.

Import the Radio and RadioGroup, a theme, and register the components:

import { defineComponents, IgcRadioComponent, IgcRadioGroupComponent } from 'igniteui-webcomponents';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

defineComponents(IgcRadioComponent, IgcRadioGroupComponent);

After registration, place the Web Components Radio components inside a Radio Group and give the group a name, so that users can select only one of the options. Set value on each radio button to identify the selected option.

<igc-radio-group name="fruit">
  <igc-radio value="apple" checked>Apple</igc-radio>
  <igc-radio value="banana">Banana</igc-radio>
  <igc-radio value="mango">Mango</igc-radio>
</igc-radio-group>

The Web Components Radio components are mutually exclusive only when they share a name. The Radio Group applies its name to every radio button it contains; radio buttons without a name act independently of each other.

Prerequisites and Version Compatibility

The Web Components Radio and Radio Group ship in the following package. The samples in this topic are built with the version listed next to it.

Package Version used in the samples
igniteui-webcomponents 7.4.1

Usage

Layout

The Web Components Radio places its label after the radio control by default. Set the labelPosition property to before to place the label before the control. In a vertical Radio Group, radio buttons with the label before the control align to the end of the group.

Place the radio buttons as direct children of the Radio Group. Radio buttons inside a wrapper element aren’t part of the group, and the group doesn’t lay them out.

<igc-radio-group name="color">
  <igc-radio value="yellow" label-position="before" checked>Yellow</igc-radio>
  <igc-radio value="orange" label-position="before">Orange</igc-radio>
</igc-radio-group>

A radio button can also be labelled by an element outside of it. Reference the element with aria-labelledby when you need full control over where the label sits and how it looks.

The outside element names the radio button in igniteui-webcomponents 7.4.1 and later. In earlier versions, the radio button gets no accessible name from it.

<span id="radio-label">Express delivery</span>
<igc-radio aria-labelledby="radio-label" value="express"></igc-radio>

Orientation

The Web Components Radio Group stacks its radio buttons in a column or places them in a row. Set the alignment property to vertical or horizontal. The default alignment is vertical.

<igc-radio-group name="chart" alignment="horizontal">
  <igc-radio value="line" checked>Line</igc-radio>
  <igc-radio value="bar">Bar</igc-radio>
  <igc-radio value="pie">Pie</igc-radio>
</igc-radio-group>

Interaction States

The Web Components Radio shows a hover state when the pointer is over it and a focus ring when it receives keyboard focus. Set the invalid property to show the invalid state, which draws the radio control in the error color of the theme.

<igc-radio value="daily" invalid>Daily Updates</igc-radio>

The following sample shows the hover, focused, and focused and hovered states for checked, unchecked, and invalid radio buttons.

Disabled States

Set the disabled property to disable a Web Components Radio. A disabled radio button can’t be selected, and keyboard navigation skips it.

<igc-radio-group name="age">
  <igc-radio value="18-27" checked>18-27</igc-radio>
  <igc-radio value="28-39">28-39</igc-radio>
  <igc-radio value="40-55" disabled>40-55</igc-radio>
</igc-radio-group>

On/Off States

A Web Components Radio is either on (checked) or off. Set the checked property on a radio button to turn it on, or set the value of the Radio Group to turn on the radio button with the matching value. Turning a radio button on turns off the other radio buttons in the group.

<igc-radio-group name="age" value="18-27">
  <igc-radio value="18-27">18-27</igc-radio>
  <igc-radio value="28-39">28-39</igc-radio>
  <igc-radio value="40-55">40-55</igc-radio>
</igc-radio-group>

Forms

The Web Components Radio submits the value of the selected radio button under the group’s name. Set the required property on a radio button of the group to require a selection before the form is submitted.

To show a message when the selection is missing, put it in the value-missing slot of a radio button. The required selection makes every radio button of the group invalid, so place the message in the last radio button to show it below the group.

<form>
  <igc-radio-group name="fruit">
    <igc-radio value="apple" required>Apple</igc-radio>
    <igc-radio value="banana">Banana</igc-radio>
    <igc-radio value="orange">
      Orange
      <span slot="value-missing">Choose a fruit.</span>
    </igc-radio>
  </igc-radio-group>
</form>

Do/Don’t

When extending a Radio Group with additional items, make sure that they are aligned consistently and form a single column. Avoid layout in multiple columns, as well as situations with more than one Radio element with on state at a time.

Do: list the radio buttons of a group in a single column with one option on. Don't: split them into multiple columns or turn on more than one option.

Properties

The following properties cover the Web Components Radio and Radio Group options documented on this page. See the API references for the complete generated list.

Name Type Default Description
checked boolean false Gets or sets whether the radio button is on.
disabled boolean false Gets or sets whether the radio button is disabled.
invalid boolean false Gets or sets whether the radio button is in the invalid state.
labelPosition ToggleLabelPosition after Sets whether the label is placed before or after the radio control.
required boolean false Gets or sets whether a selection is required.
value string — Gets or sets the value submitted with the form when the radio button is on.
alignment (Radio Group) ContentOrientation vertical Sets whether the radio buttons are stacked in a column or placed in a row.
value (Radio Group) string — Gets or sets the value of the radio button that is on.
name string — Gets or sets the name that groups radio buttons together.
name (Radio Group) string — Gets or sets the name applied to all radio buttons in the group.

Methods

The Web Components Radio exposes the following methods.

Name Description
checkValidity() Checks the validity of the radio button and returns true when it’s valid.
reportValidity() Checks the validity of the radio button, shows its invalid state when it isn’t valid, and returns true when it’s valid.
setCustomValidity(message) Sets a custom validation message. Pass an empty string to clear it.
click() Simulates a click on the radio button, which turns it on.
focus() Moves focus to the radio button.
blur() Removes focus from the radio button.

Events

The Web Components Radio emits an event when the user turns a radio button on.

Name Description
igcChange Emitted when the checked state of a radio button changes. The event arguments carry the checked state and the value of the radio button.

Styling

The Web Components Radio is styled through the Ignite UI for Web Components theme and the CSS variables it generates. CSS parts give you access to the internal elements of the radio button. The following sample draws the radio buttons of a shipping form with a custom palette and typeface.

Sass Theming

Create a theme with the radio-theme function and include it with the tokens mixin. Setting $empty-color and $fill-color is enough for a fully styled radio button, because the theme derives the remaining colors from them.

@use "igniteui-theming" as *;

$custom-radio-theme: radio-theme(
  $empty-color: #345779,
  $fill-color: #2dabe8,
);

:root {
  @include tokens($custom-radio-theme);
}

When you set a primary parameter, the theme derives its dependent parameters:

Primary parameter Dependent parameters What it changes
$empty-color $hover-color, $focus-outline-color (Indigo) The border of an unchecked radio button.
$fill-color $fill-color-hover, $fill-hover-border-color, $focus-border-color (Bootstrap), $focus-outline-color (Bootstrap), $focus-outline-color-filled (Indigo) The border and dot of a checked radio button.
$label-color $label-color-hover The label text.
$error-color $error-color-hover, $focus-outline-color-error The label, border, and dot in the invalid state.

CSS Variables

Set the following CSS variables on a radio button, or on one of its ancestors, to change its colors without a Sass theme:

Variable What it changes
--ig-radio-label-color The label text.
--ig-radio-empty-color The border of an unchecked radio button.
--ig-radio-empty-fill-color The fill of an unchecked radio button.
--ig-radio-fill-color The border and dot of a checked radio button.
--ig-radio-hover-color The border and dot on hover.
--ig-radio-fill-color-hover The dot of a checked radio button on hover.
--ig-radio-error-color The label, border, and dot in the invalid state.
--ig-radio-disabled-color The border and dot of a disabled radio button.
--ig-radio-disabled-label-color The label of a disabled radio button.
--ig-radio-focus-outline-color The focus outline.

Style Parts

Use the following CSS parts to target the internal elements of the Web Components Radio. Each part also carries the checked part name while the radio button is on, so ::part(control checked) targets only a checked radio control.

Part What it styles
base The wrapper of the radio control and the label.
control The radio control.
label The label.
igc-radio {
  --ig-radio-fill-color: #0176ff;
  --ig-radio-empty-color: #a9b8cc;
}

igc-radio::part(label) {
  color: #002b5c;
  font-weight: 600;
}

Styling with Tailwind

You can style the Web Components Radio with the custom Tailwind utility classes from igniteui-theming. Make sure to set up Tailwind first, then import the utilities in your global stylesheet:

@import "tailwindcss";
@import "igniteui-theming/tailwind/utilities/material.css";

Use the light-radio or dark-radio class for the corresponding theme and override its CSS variables with arbitrary properties:

<igc-radio class="!light-radio ![--empty-color:#576E60] ![--fill-color:#7B9E89]" value="tokyo">Tokyo</igc-radio>

The exclamation mark (!) gives the Tailwind utility precedence over the default theme styles of the Radio.

Accessibility

The Web Components Radio renders a native radio input, so assistive technologies announce each radio button with its role, label, and checked state.

Keyboard Interaction

The Web Components Radio Group moves focus and selection between its enabled radio buttons with the arrow keys. Disabled radio buttons are skipped.

Key Action
Tab / Shift+Tab Moves focus into or out of the Radio Group.
Arrow Down / Arrow Right Moves focus to the next enabled radio button and turns it on. From the last radio button, moves to the first one. In right-to-left layouts, Arrow Right moves to the previous radio button.
Arrow Up / Arrow Left Moves focus to the previous enabled radio button and turns it on. From the first radio button, moves to the last one. In right-to-left layouts, Arrow Left moves to the next radio button.
Space Turns on the focused radio button.
Enter Submits the form that contains the radio button.

When a radio button in the group is on, it is the only tab stop of the group. When none of the radio buttons is on, each of them is a tab stop.

Screen Readers / ARIA

  • Each Web Components Radio renders a native <input type="radio">, which exposes the radio role, the checked state, and the disabled and required states.

  • The label content of the radio button is its accessible name. When the label is outside the component, connect it with aria-labelledby.

  • The Radio Group renders the radiogroup role and sets aria-orientation from its alignment.

  • Give the Radio Group an accessible name, for example with aria-labelledby pointing to the question it answers.

Accessibility Compliance

Verify the rendered Web Components Radio and Radio Group against the accessibility requirements of your application.

Criterion How the component supports the requirement
2.1.1 Keyboard Users move between the enabled radio buttons and turn them on with the arrow keys and Space.
4.1.2 Name, Role, Value Each radio button exposes its label as the accessible name, the radio role, and its checked state through the native radio input.

Your responsibilities:

  • Give every radio button meaningful label content, and give the Radio Group an accessible name.
  • Keep the focus ring visible and preserve sufficient contrast when you customize the Radio colors.
  • Show a validation message when the Radio is invalid, so the error isn’t conveyed by color alone. Use the value-missing slot, as shown in Forms.
  • Test the rendered Radio Group with keyboard navigation and the assistive technologies your users rely on.

API References

Dependencies

The Web Components Radio requires a theme stylesheet to apply its visual styling. See the framework-specific setup in Getting Started.

Additional Resources

Use the following Web Components resources for API details and project support:

The Web Components Radio is intended for one choice from a short list of mutually exclusive options. Use the following related components for other kinds of choices:

  • Checkbox - Use Checkbox when users can select more than one option.
  • Switch - Use Switch when the control turns a single setting on or off immediately.
  • Select - Use Select when the list of options is long or space is limited.

FAQ

These frequently asked questions cover common Web Components Radio and Radio Group selection, form, and state scenarios.

How do I get the selected value when the user changes the selection?

Handle the igcChange event on the Web Components Radio Group. The change event arguments carry the value of the radio button the user turned on. The change event doesn’t fire when you set the Radio Group value in code.

How do I select a radio button from code?

Set the Web Components Radio Group value to the value of the radio button you want to turn on. You can also set checked on that radio button, which turns off the other radio buttons in the group. Selecting a radio button in code doesn’t fire the change event.

How do I clear the selection of a Radio Group?

Users can’t turn off a selected Web Components Radio by clicking it again, which is the standard radio button behavior. To clear the selection in code, set the Radio Group value to an empty string or another value that none of its radio buttons has. If users need to clear the selection themselves, add a “None” option or a separate clear button.

Why can more than one radio button be on at the same time?

Web Components Radio buttons are mutually exclusive only when they share the same name, so radio buttons without a shared name can be on at the same time. Set name on the Radio Group, which applies it to all of its radio buttons, or set the same name on each radio button.

How do I make a selection required in a form?

Set required on any radio button of the Web Components Radio Group, and the whole group requires a selection before the form can be submitted. When the form is submitted, the group’s name is sent with the value of the selected radio button.

How do I disable all radio buttons of a Radio Group?

The Web Components Radio Group doesn’t have a disabled property of its own. To disable the whole group, set disabled on each of its radio buttons, for example by binding all of them to the same state.