a11ytools
aria-roles
aria-roles is a lightweight utility library that provides a reliable way to fetch valid ARIA roles dynamically. It simplifies accessibility development by preventing hardcoded role values and enabling validation for better UI accessibility compliance.
🚀 Features
- 📜 Retrieve a complete, up-to-date list of all valid ARIA roles
- ✅ Validate whether a given role is a recognized ARIA role
- 🔒 Type-safe access to ARIA role names
- ⚡ Lightweight, fast, and dependency-free
- 🔍 Designed for use in accessibility tooling, testing, and frontend frameworks
📦 Installation
npm install @a11y-tools/aria-roles🔧 Usage
Basic Usage
import { getAllAriaRoles, isValidAriaRole, ariaRoles } from "@a11y-tools/aria-roles";
// Get all valid ARIA roles
console.log(getAllAriaRoles()); // Returns an array of valid ARIA roles
// Validate a role
console.log(isValidAriaRole("button")); // true
console.log(isValidAriaRole("fake-role")); // false
// Type-safe access to role names
element.setAttribute('role', ariaRoles.button);
element.setAttribute('role', ariaRoles.tabpanel);TypeScript Usage
import { AriaRole, ariaRoles, isValidAriaRole } from "@a11y-tools/aria-roles";
// Type-safe role definition
const myRole: AriaRole = ariaRoles.button;
// Type narrowing with isValidAriaRole
function setRole(element: HTMLElement, role: string) {
if (isValidAriaRole(role)) {
// TypeScript knows 'role' is of type AriaRole here
element.setAttribute('role', role);
} else {
console.warn(`Invalid ARIA role: ${role}`);
}
}React Example
import React from 'react';
import { ariaRoles } from '@a11y-tools/aria-roles';
function AccessibleButton({ children, onClick }) {
return (
<div
role={ariaRoles.button}
onClick={onClick}
tabIndex={0}
onKeyDown={(e) => {
if (e.key === 'Enter' || e.key === ' ') {
onClick();
}
}}
>
{children}
</div>
);
}Vue Example
<template>
<div
:role="ariaRoles.button"
@click="onClick"
tabindex="0"
@keydown="handleKeyDown"
>
<slot></slot>
</div>
</template>
<script>
import { ariaRoles } from '@a11y-tools/aria-roles';
export default {
setup() {
const handleKeyDown = (e) => {
if (e.key === 'Enter' || e.key === ' ') {
onClick();
}
};
return {
ariaRoles,
handleKeyDown
};
},
methods: {
onClick() {
// Handle click
}
}
}
</script>🧪 Testing Example
import { render, screen } from '@testing-library/react';
import { ariaRoles, isValidAriaRole } from '@a11y-tools/aria-roles';
// React Testing Library - use ariaRoles for type-safe queries
test('Component uses correct ARIA roles', () => {
render(<MyComponent />);
// Query elements by their roles using ariaRoles
const button = screen.getByRole(ariaRoles.button);
const navigation = screen.getByRole(ariaRoles.navigation);
// Verify elements have proper attributes
expect(button).toHaveAttribute('aria-pressed', 'false');
expect(navigation).toBeInTheDocument();
});
// Validate all roles in a component
test('All roles are valid', () => {
const { container } = render(<MyComponent />);
// Check that all role attributes are valid
container.querySelectorAll('[role]').forEach(element => {
const role = element.getAttribute('role');
expect(isValidAriaRole(role)).toBe(true);
});
});🔄 API Reference
getAllAriaRoles()
Returns an array of all valid ARIA roles as strings.
function getAllAriaRoles(): AriaRole[]isValidAriaRole(role)
Validates if a string is a valid ARIA role. In TypeScript, this function acts as a type guard.
function isValidAriaRole(role: string): role is AriaRoleariaRoles
An object that provides type-safe access to all ARIA role names. Each property is named after an ARIA role and returns the role name as a string.
const ariaRoles: Record<AriaRole, AriaRole>AriaRole (TypeScript only)
A TypeScript type that represents all valid ARIA roles.
type AriaRole = 'alert' | 'alertdialog' | 'application' | /* ... */;🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
📜 License
This project is licensed under the MIT License.