Widget Roles — Button, Link, Checkbox, Radio and Tab

In this tutorial, you will learn about Widget Roles. We cover key concepts, practical examples, and best practices to help you master this topic.

ARIA widget roles like button, link, checkbox, radio, and tab identify interactive elements to assistive technologies, providing the semantics for user interaction patterns.

In this tutorial, you'll learn how to implement common widget roles correctly in ARIA.

What You'll Learn

By the end of this lesson, you'll understand the key widget roles, their required states, keyboard interaction patterns, and how to implement them with proper focus management.

Why It Matters

Widget roles are the foundation of accessible custom controls. Users expect consistent behavior from buttons, checkboxes, and radios regardless of how they are implemented.

Real-World Use

Doda Browser's settings panel uses custom checkboxes and radio buttons to match the brand design while maintaining full Accessibility.

Widget Role Categories

flowchart TD
  A[Widget Roles] --> B[Button]
  A --> C[Link]
  A --> D[Checkbox]
  A --> E[Radio]
  A --> F[Tab]
  A --> G[Switch]
  A --> H[Slider]
  B --> I[Click, Enter, Space]
  D --> J[Toggle aria-checked]
  E --> K[Select one from group]
  F --> L[Select, controls panel]

Button Role

A button triggers an action when activated. Use native <button> first, but when you cannot, use role="button":

<div role="button" tabindex="0" onclick="startScan()" onkeydown="if(event.key==='Enter'||event.key===' ')startScan()">
  Start Scan
</div>

Required: tabindex="0", keyboard handlers for Enter and Space.

Checkbox Role

A checkbox represents a binary choice. It requires aria-checked:

<div role="checkbox" aria-checked="false" tabindex="0" onclick="toggleCheck(this)" onkeydown="if(event.key===' ')toggleCheck(this)">
  Enable notifications
</div>

function toggleCheck(checkbox) {
  const checked = checkbox.getAttribute('aria-checked') === 'true';
  checkbox.setAttribute('aria-checked', !checked);
}

Radio Role

Radio buttons are grouped with radiogroup. Only one can be selected:

<div role="radiogroup" aria-label="Scan type">
  <div role="radio" aria-checked="true" tabindex="0">Quick Scan</div>
  <div role="radio" aria-checked="false" tabindex="-1">Full Scan</div>
  <div role="radio" aria-checked="false" tabindex="-1">Custom Scan</div>
</div>

Tab Role

Tabs work in pairs: tab inside tablist controls a tabpanel:

<div role="tablist" aria-label="Settings">
  <button role="tab" aria-selected="true" aria-controls="general" tabindex="0">General</button>
  <button role="tab" aria-selected="false" aria-controls="security" tabindex="-1">Security</button>
</div>
<div role="tabpanel" id="general">General settings...</div>
<div role="tabpanel" id="security" hidden>Security settings...</div>

Common Mistakes

• Missing keyboard handlers for button role: role="button" does not add keyboard support.
• Not grouping radios in a radiogroup: Without radiogroup, the radio relationship is lost.
• Using checkbox role without aria-checked: The checked state must be explicit.
• Forgetting aria-controls on tabs: The tab needs to reference its panel.
• Not managing tabindex in roving widget patterns: Only the active item should be in the tab order.

Practice and Challenge

1. What widget role requires aria-checked? checkbox, switch, menuitemcheckbox, and radio.

2. What keyboard keys activate a button role? Enter and Space.

3. How do you group radio buttons? Wrap them in a radiogroup role.

4. What attribute links a tab to its panel? aria-controls on the tab referencing the panel's ID.

5. Challenge: Build a custom radio group with three options. Implement proper tabindex management so only the selected radio is in the tab order.

FAQ