ARIA role required attributes
Look up an ARIA role and get its exact contract: checkbox requires aria-checked, has 8 recommended attributes such as aria-label and aria-invalid, and needs an accessible name. Based on WAI-ARIA 1.2, with unknown roles refused. Free in your browser.
- Free
- Runs in your browser
- No sign-up
- Your data stays on your device
Run — free
Worked example
- Role
- checkbox
- Category
- widget
- Superclass
- input
- Required attributes
- aria-checked
- Required count
- 1
Accessible Rich Internet Applications (ARIA) defines dozens of roles so custom widgets can expose the same meaning as native HTML controls. Each role carries a fixed contract: some states and properties are required, others are recommended for real-world assistive technology support, and many roles also demand an accessible name. Guessing those attributes from memory is a common source of audit failures—missing aria-checked on a checkbox role, forgetting aria-controls on a combobox, or shipping a region landmark without a label. This capability accepts a single ARIA role name, normalizes casing and common prefixes, and returns a deterministic package: required attributes, recommended attributes, category, superclass, name requirements, and a short description grounded in WAI-ARIA 1.2.
Why guessing ARIA attributes fails audits
ARIA defines dozens of roles so that custom controls can expose the same meaning as native HTML elements. Each role carries a fixed contract: some states and properties are required, others are recommended for real support in assistive technology, and many roles also demand an accessible name. Remembering all of that by heart is a common source of audit failures: a checkbox role without aria-checked, a combobox without aria-controls and aria-expanded, a slider without aria-valuenow, or a region landmark shipped without a label. Each of those fails automated checks and leaves screen reader users with a control that does not say what it is or what state it is in.
What one lookup tells you
Type a single role name, in any capitalisation and with or without a prefix; even «column header» and «columnheader» lead to the same role. You get its required and recommended attributes, its category, the broader role it inherits from, whether it needs an accessible name and how that name may be computed, plus a short description based on WAI-ARIA 1.2. For checkbox, that means aria-checked as the only requirement, 8 recommended attributes and the description of an input with three possible values: true, false or mixed. A scrollbar comes back with four required properties: aria-controls, aria-valuenow, aria-valuemin and aria-valuemax. Notes appear when a requirement depends on context, as with a focusable separator, which needs its value attributes while a decorative one does not.
What required and recommended ARIA attributes mean
In the WAI-ARIA specification every concrete role lists Required States and Properties—attributes the author must supply for the role to be valid—and Supported States and Properties that assistive technologies expect when the pattern needs richer state. Required attributes are non-negotiable: a role of checkbox without aria-checked, a slider without aria-valuenow, or a combobox without aria-controls and aria-expanded fails automated checks and confuses screen readers. The response also reports whether the role requires an accessible name and how that name may be computed (author-provided attributes, element contents, or prohibited).
Deprecated concrete roles such as directory remain queryable but are flagged so migration tools can warn without blocking the lookup.
What you can do with it
CI accessibility lint oracles
Given role values scraped from markup or Storybook, assert that every required attribute is present before merge; fail on abstract or unknown roles.
FAQ
Which ARIA attributes are required for a given role?
Send the role name (for example checkbox, combobox, slider).
Does this validate my HTML page?
No. It only looks up specification characteristics for one role name. Use an accessibility auditor (for example web.accessibility) to scan live markup.
What is the difference between required and recommended attributes?
Required attributes must be present for the role to be valid: a checkbox without aria-checked fails automated checks and confuses screen readers. Recommended ones are those assistive technologies expect when the pattern needs richer state, such as disabled, read-only or error messages.
Does a checkbox role need an accessible name?
Yes. The lookup reports that the name is required and that it can come from the element's own content or from the author, for example through aria-label or aria-labelledby when the visible text is not enough.
What happens with deprecated or abstract roles?
Deprecated roles such as directory can still be looked up but are flagged, so a migration tool can warn without blocking. Abstract roles and unknown names are refused, so nobody ends up adding attributes for a role that does not exist.
Related tools
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/web/aria-role-lookup \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"role":"checkbox"}'const res = await fetch("https://api.kit.forhosting.com/web/aria-role-lookup", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"role": "checkbox"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/web/aria-role-lookup",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"role": "checkbox"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/web/aria-role-lookup", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"role":"checkbox"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"role":"checkbox"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/web/aria-role-lookup", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"role": "checkbox"
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "web.aria_role_lookup",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Limits
timeout_sec | 30 |
max_crawl_pages | 25 |
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |
Technical notes
Unrecognized names and abstract roles fail with invalid_input so callers never invent attributes for roles that do not exist. The same pure table powers the free browser tool and the prepaid API at $0.002 per successful item.
What required and recommended ARIA attributes mean
Recommended attributes in this API are the supported properties authors most often need for correct keyboard and AT behaviour: selection and expansion flags, value min and max for range widgets, orientation for toolbars and tablists, and naming helpers such as aria-label and aria-labelledby when the visible text is insufficient.
Input contract, response shape, and error behaviour
Optional notes appear when a requirement is conditional—for example a focusable separator needs aria-valuenow, aria-valuemin, and aria-valuemax even though a static decorative separator does not. Example: role checkbox returns required aria-checked and a recommended set covering readonly, required, disabled, labelling, and error messaging attributes. Example: role scrollbar returns the four required properties aria-controls, aria-valuenow, aria-valuemin, and aria-valuemax. POST a JSON body with one required string field, role, which may also arrive under the aliases value, name, query, or aria_role. The engine trims whitespace, lowercases the token, strips optional prefixes like role= or aria-role, and removes internal spaces or underscores so column header and columnheader both resolve. On success the body echoes the normalized role, category, superclass, description, abstract false, required_attributes and recommended_attributes as sorted string arrays, required_count and recommended_count, name_required, name_from, deprecated, and spec set to WAI-ARIA 1.2. Missing role, empty string, unknown names, and abstract roles throw invalid_input with a message that names the problem; those failures are not billed. Pair the lookup with your own lint or design-system documentation; this endpoint does not crawl a page or validate live markup—it only answers the specification question for one role name at a time.
Where an ARIA role attribute lookup earns its keep
Training platforms and WCAG courses use the free browser path so students can explore checkbox versus switch, or dialog versus alertdialog, without memorizing the full characteristics tables. Keep role names in your tests pinned to the returned sorted arrays, document abstract-role rejections for authors who copy taxonomy names by mistake, and you get a stable contract for styleguides, MCP tools, and edge validators without standing up a full accessibility engine. Accessibility linters and CI plugins call the API as an oracle: given the role string found on a node, fetch required attributes and fail the build when any are absent.
Integration use cases
Design-system documentation
Generate per-component ARIA tables from the role string so engineers see required and recommended attributes next to the React or Web Component API.
Training and WCAG workshops
Let learners look up checkbox, combobox, and region interactively and compare name_required rules without memorizing the full WAI-ARIA tables.
Technical questions
What happens if the role name is unknown?
The task fails with invalid_input and a message that the role is unrecognized. Abstract roles such as widget or landmark are also rejected because authors must not use them.
Is the lookup case-sensitive?
No. Role names are normalized to lowercase; optional prefixes like role= are stripped, and spaces or underscores inside the token are removed.
What does the ARIA role attribute lookup cost?
The browser tool is free. API requests use prepaid KIT balance at $0.002 per successful call; invalid input is not billed.