ARIA Implementation Patterns

ARIA Implementation Patterns

Systematic procedure for implementing ARIA roles, states, and properties when native HTML is insufficient.

Pre-Implementation Checklist

CRITICAL: Complete this checklist before proceeding with ARIA implementation.

• Verified native HTML element cannot meet requirements
• Checked if ShadCN/Radix has this component
• Identified matching W3C APG pattern
• Understand complete keyboard behavior required for this pattern
• Ready to implement full accessibility, not just add role attribute

If any checkbox is unchecked, reconsider whether ARIA is necessary.

Step 1: Verify Native HTML Won't Work

Question: Can this be accomplished with native HTML?

Native HTML Elements:

• Button → <button>
• Checkbox → <input type="checkbox">
• Radio group → <input type="radio" name="group">
• Select → <select> and <option>
• Link → <a href>
• Text input → <input type="text">
• Number input → <input type="number">
• Range slider → <input type="range">
• Date picker → <input type="date">
• Details/summary → <details> and <summary>

Only Proceed with ARIA If:

1. Native element doesn't exist

   • Examples: tabs, tree view, breadcrumb, toolbar

2. Native element lacks required behavior

   • Example: Combobox with search/autocomplete (native <select> doesn't support)
   • Example: Multi-level menu with keyboard shortcuts

3. Design requires visual customization impossible with native elements

   • Example: Custom-styled select that must match brand guidelines
   • Note: Try CSS styling of native elements first

Decision Tree

Can native HTML do this?
├─ Yes → Use native HTML (STOP, do not use ARIA)
└─ No → Does ShadCN/Radix have this?
    ├─ Yes → Use ShadCN/Radix component (STOP, do not use ARIA)
    └─ No → Continue to Step 2

Step 2: Select Appropriate APG Pattern

Common Patterns Requiring ARIA

Reference composite-widgets-guide.md for detailed implementation of each pattern.