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.
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.

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
radiogrouprole and setsaria-orientationfrom itsalignment. -
Give the Radio Group an accessible name, for example with
aria-labelledbypointing 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-missingslot, 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:
Related Components
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.
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.
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.
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.
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.
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.
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.