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.
Example 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"
  ></nys-radiobutton>
  <nys-radiobutton
    name="office"
    label="Manhattan"
    description="New York City"
    value="manhattan"
  ></nys-radiobutton>
</nys-radiogroup>

Options

Disabled

Example Code 
<nys-radiogroup label="Current Title:" description="Note: You cannot change your title.">
  <nys-radiobutton disabled name="title" label="Software Engineer 1" description="<1 year experience" value="eng-1" checked ></nys-radiobutton>
  <nys-radiobutton disabled name="title" label="Software Engineer 2" description="1-3 years experience" value="eng-2"></nys-radiobutton>
  <nys-radiobutton disabled name="title" label="Software Engineer 3" description="3-5 years experience" value="eng-3"></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.
Example Code 
<nys-radiogroup size="sm" label="Select your agency" description="This is the agency, department, or office you work for.">
  <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>

Error

To display an error message, pass in the showError property to the nys-radiogroup component. Setting errorMessage does not display the message without showError set to true.

Example Code 
<nys-radiogroup required showError errorMessage="You must select one of the above options to continue" 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-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.

Example 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 set of nys-radiobuttons 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
name string
label string
description string
value string
id string
checked boolean
size string ("sm", "md")
disabled boolean
form string
required boolean
showError boolean
errorMessage string

CSS Variables


Events

The nys-radiobutton component emits four custom Javascript events:

  1. change – Fired when the radiobutton state changes (checked/unchecked).
  2. focus – Fired when the radiobutton gains focus.
  3. blur – Fired when the radiobutton loses focus.
  4. keydown – Fired when a key is pressed while the radiobutton is focused.

You can listen to these events using JavaScript:

// Select the radiobutton component
  const radiobutton = document.querySelector('nys-radiobutton');

  // Listen for the 'change' event
  radiobutton.addEventListener('change', (event) => {
    console.log('Radio Button changed:', event.target.checked);
  });