Components

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.

<nys-radiogroup 
  label="What is your primary work location?" 
  description="This is the location you use for your in office days." 
>
  <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.

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.

Additional accessibility test and build content is coming soon, in a new format.

Options

Partial

<nys-radiogroup label="Choose your preferred work operating system.">
  <nys-radiobutton
    name="op-system"
    label="Windows 11"
    description="HP Elitebook"
    value="windows"
  ></nys-radiobutton>
  <nys-radiobutton
    name="op-system"
    label="Sequoia"
    description="Macbook Air"
    value="mac"
  </nys-radiobutton>
  <nys-radiobutton
    name="op-system"
    label="Linux"
    value="windows"
    disabled
  </nys-radiobutton>
</nys-radiogroup>

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>

Other

Use the other option to allow a custom response when none of the listed choices apply. When selected, a text input appears and the <nys-radiobutton> value becomes whatever the user enters.

If no label is provided, it defaults to “Other.” You can provide a custom label such as “Something else” or “Other (please specify).”

Note: Place this option as the last <nys-radiobutton> within <nys-radiogroup>.

<nys-radiogroup label="What is your primary work location?" description="This is the location you use for your in office days.">
  <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-radiobutton
    name="office"
    other
  ></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. Note: The showError attribute is a boolean that toggles automatically based on other validation. setting showError to true manually will only set the error message to be visible on initial render, once the user interacts with the component, showError will toggle based on validation rules (e.g., required, pattern, etc.)

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

Inverted

Set the inverted on <nys-radiogroup> when the component is on a dark background.

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

New York City (slot)

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

Usage

Do

Use when a user needs to select only one option from a list of 7 or fewer choices.
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. Don't leave all options unselected if a helpful default can guide users.
Use concise, descriptive labels for each option.

Don't

Use when users need to select multiple options. Use checkboxes instead.
Use when there are more than 7 options. Use a dropdown for better space utilization.
Use for yes/no questions. Consider <nys-toggle> or <nys-checkbox> instead.

Properties

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

Form Prop

The form property associates this component with a <form> element by ID, even if the component is not a descendant of that form. See Form Patterns for details on form association and ElementInternals.

Style Overrides

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:

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.

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:

// 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: June 26, 2026