Radiobutton

The <nys-radiobutton> component is a reusable web component for use in New York State digital products. It 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.

<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 NYSDS web components in your project? Try using the CSS Variables instead.

Options

Disabled

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

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

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

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

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

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

This is the location you use for your in office days.

A part of Upstate New York

A part of New York City

<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.
Use a clear default selection if applicable (e.g., the most common or recommended choice).
Provide descriptive and concise labels for each option.
Group related radio buttons with a heading or contextual instructions to clarify the choice.

Don't

Use radio buttons for yes/no questions (consider a toggle or checkbox).
Overload the user with too many radio button options; simplify or use a dropdown if needed.
Leave all radio buttons unselected if a default selection would help 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	both
`label`	String	both
`value`	String	only `<nys-radiobutton>`
`checked`	boolean	only `<nys-radiobutton>`
`disabled`	boolean	only `<nys-radiobutton>`
`form`	String	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>`

CSS Variables

Events

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

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

You can listen to these events using JavaScript:

// Select the radiobutton component
const radiobutton = document.querySelector('nys-radiobutton');
// Listen for the 'nys-change' event
radiobutton.addEventListener('nys-change', (event) => {
  console.log('Radio Button changed:', event.detail.checked);
});

Suggest a New Component

Do you have an idea for a new NYSDS 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.