Radio Button

The <nys-radiobutton> provides users with the ability to choose from a group of options. Only one option can be selected at a time.

Note: <nys-radiogroup> must be used to wrap multiple radio buttons so they function as a single form control.

Copy Code
<nys-radiogroup label="What is your primary work location?" description="This is the location you use for your in office days." size="md">
  <nys-radiobutton name="office" label="Albany" description="Upstate New York" value="albany" checked></nys-radiobutton>
  <nys-radiobutton name="office" label="Manhattan" description="New York City" value="manhattan"></nys-radiobutton>
</nys-radiogroup>

Can't use NYS design System web components in your project? Try using the CSS Variables instead.


Options

Disabled

Copy Code
<nys-radiogroup label="Current Title:" description="Note: You cannot change your title.">
  <nys-radiobutton name="title" label="Software Engineer 1" description="<1 year experience" value="eng-1" checked disabled></nys-radiobutton>
  <nys-radiobutton name="title" label="Software Engineer 2" description="1-3 years experience" value="eng-2" disabled></nys-radiobutton>
  <nys-radiobutton name="title" label="Software Engineer 3" description="3-5 years experience" value="eng-3" disabled></nys-radiobutton>
</nys-radiogroup>

Required

Set required to <radiogroup> to make selecting an option mandatory.

Copy Code
<nys-radiogroup label="What is your primary work location?" description="This is the location you use for your in office days." required>
  <nys-radiobutton name="office" label="Albany" description="Upstate New York" value="albany"></nys-radiobutton>
  <nys-radiobutton name="office" label="Manhattan" description="New York City" value="manhattan"></nys-radiobutton>
</nys-radiogroup>

Optional

Adding the optional prop will add an optional flag to the input.

Copy Code
<nys-radiogroup label="What is your primary work location?" description="This is the location you use for your in office days." optional>
  <nys-radiobutton name="office" label="Albany" description="Upstate New York" value="albany"></nys-radiobutton>
  <nys-radiobutton name="office" label="Manhattan" description="New York City" value="manhattan"></nys-radiobutton>
</nys-radiogroup>

Size

Set the size prop of the <nys-radiogroup> to have all <nys-radiobutton> be the same size. Our current sizes are:

  • sm: Set to 24px in width and height
  • md: The default size. Set to 32px in width and height.
Copy Code
<nys-radiogroup label="Select your agency" description="This is the agency, department, or office you work for." size="sm">
  <nys-radiobutton name="agency" checked label="Department of Health" value="doh" ></nys-radiobutton>
  <nys-radiobutton name="agency" label="Office of Information Technology Services" value="its" ></nys-radiobutton>  
  <nys-radiobutton name="agency" label="Office of the New York State Attorney General" value="ag" ></nys-radiobutton>
</nys-radiogroup>

Tile

The tile prop will change the styling of the radio button to a tile. This is useful when you want a larger clickable area for the user.
Note: The tile prop is applied to the <nys-radiogroup> component, not the <nys-radiobutton>. Each <nys-radiobutton> in the <nys-radiogroup> will be set to tile.

Copy Code
<nys-radiogroup label="Select your agency" description="This is the agency, department, or office you work for." tile>
  <nys-radiobutton name="agency" checked label="Department of Health" value="doh"></nys-radiobutton>
  <nys-radiobutton name="agency" label="Office of Information Technology Services" value="its"></nys-radiobutton>  
  <nys-radiobutton name="agency" label="Office of the New York State Attorney General" value="ag" disabled></nys-radiobutton>
</nys-radiogroup>

Error

To display an error message, pass in the showError property to the <nys-radiogroup> component. Set an error message and choose to activate it. Setting errorMessage does not display the message without boolean prop showError.

Copy Code
<nys-radiogroup label="What is your primary work location?" description="This is the location you use for your in office days." required showError errorMessage="You must select one of the above options to continue">
  <nys-radiobutton name="office" label="Albany" description="Upstate New York" value="albany" ></nys-radiobutton>
  <nys-radiobutton name="office" label="Manhattan" description="New York City"  value="manhattan"></nys-radiobutton>
</nys-radiogroup>

Slotted Description

When the description requires more complexity than a simple string, use the description slot to hold the text. This allows the developer to include HTML in the description, such as anchors or bold text.

Both <nys-radiobutton> and <nys-radiogroup> support the description slot.

Copy Code
<nys-radiogroup label="What is your primary work location?">
  <label slot="description">This is the location you use for your <a href="https://www.ny.gov/" target="__blank">in office days.</a></label>
  <nys-radiobutton name="office" label="Albany" value="albany">
    <label slot="description">A part of <a href="https://www.ny.gov/" target="__blank">Upstate New York</a></label>      
  </nys-radiobutton>
  <nys-radiobutton name="office" label="Manhattan" value="manhattan">
    <label slot="description">A part of <a href="https://www.ny.gov/" target="__blank">New York City</a></label>      
  </nys-radiobutton>
</nys-radiogroup>

Usage

When to use this component

  • When the user needs to select only one option from a list.
  • When there are 7 or fewer options to choose from (for better usability).

When to consider something else

  • When users need to select multiple options (consider checkboxes instead).
  • When there are more than 7 options (consider a dropdown for better space utilization).

Do

  • Always wrap a group of <nys-radiobutton> with a <nys-radiogroup>
  • Group radio buttons vertically for easier scanning, especially when labels are lengthy.
  • Set a clear default when one choice is recommended or most common.
  • Use concise, descriptive labels for each option.
  • Group related options under a heading or instruction to provide context.

Don't

  • Don't use radio buttons for yes/no questions (consider using <nys-toggle> or <nys-checkbox>).
  • Don’t overload users with too many options; simplify or use a dropdown instead.
  • Don’t leave all options unselected if a helpful default can guide users.

Accessibility

The <nys-radiobutton> component includes the following accessibility-focused features:

  • Proper ARIA roles and attributes to ensure screen readers can interpret the radiobutton correctly.
    • aria-checked
    • aria-disabled
    • aria-required
  • Keyboard navigation support, allowing users to toggle the radiobutton using the keyboard.
  • Visual focus indicators to help users navigate the component.
  • Include a label property to provide accessible text for screen readers.

Properties

Property Type Component
id String both
name String only <nys-radiobutton>
label String both
value String only <nys-radiobutton>
checked boolean only <nys-radiobutton>
disabled boolean only <nys-radiobutton>
description String both
errorMessage String only <nys-radiogroup>
optional boolean only <nys-radiogroup>
required boolean only <nys-radiogroup>
showError boolean only <nys-radiogroup>
size "sm" | "md" only <nys-radiogroup>
tile boolean only <nys-radiogroup>
form String | null only <nys-radiogroup>

CSS Variables

There are no existing CSS variables for this component. Explore existing options, or propose a new one with a Component Proposal.


Events

The <nys-radiogroup> component emits three custom Javascript events:

  1. nys-change – Fired when the radiobutton state changes (checked/unchecked).
  2. nys-focus – Fired when the radiobutton gains focus.
  3. nys-blur – Fired when the radiobutton loses focus.

Event details

The nys-change event includes a detail object with the following properties:

  • id (string): The id of the radiobutton.
  • checked (boolean): Whether the radiobutton is selected.
  • name (string): The radiobutton group name.
  • value (string): The radiobutton’s value.

You can listen to these events using JavaScript:

Copy Code
// Select the radiogroup component
const radiogroup = document.querySelector('nys-radiogroup');
// Listen for the 'nys-change' event
radiogroup.addEventListener('nys-change', (event) => {
  const { id, checked, name, value } = event.detail;
  console.log(`Radiobutton with id="${id}" in group "${name}" was selected. Value="${value}", checked=${checked}`);
});

Suggest a New Component

Do you have an idea for a new NYS Design System web component? Look through the existing proposals in our GitHub discussions board to see if someone already proposed something similar. If not, feel free to submit one.

Edit this page on GitHub (Permissions required)

Last updated: October 30, 2025