Custom widgets often ship a role but omit the matching state properties

What it is

Put role="checkbox" or role="combobox" on a div and the reader will introduce it as that widget and expect to speak checked, expanded, pressed. An incomplete ARIA widget is a role that already claims “I am this control” while the matching state properties are missing. The user hears “checkbox,” asks whether it is ticked, and gets silence — not “not checked.”

The miss is not “forgot the name,” and not “state changed but the tree lagged.” There is no property to keep in sync. The role created an expectation; the state slot is empty.

Why it happens

A role is a contract. checkbox includes checked; combobox includes expanded and hasPopup; tab includes selected; switch includes checked; a toggle button includes pressed. The reader uses the contract to decide what to speak and which keyboard model to assume. When the property is absent, most readers do not invent a default and speak it; they omit that item from speech. The role still manufactures “this is a checkbox”; the state channel has no payload.

The second layer is reuse inside design systems. A library lays down the role so inspectors recognise the widget; state binding is left for product code “when we get to it.” Inspectors see a role and automated rules go green. The gap shows the first time a user asks “is this on or off.”

Studying it

Sample custom controls: anything whose role is not the host default. Build a table of required and supported states per role from WAI-ARIA. Read each instance in the inspector and with NVDA: is the role spoken, does a state word appear, does the keyboard model match the role. Compare a native element with the same job.

Independent variables: role kind, presence of required states, presence of supported states the product actually uses. Dependent variables: whether speech includes state, whether a user can answer “which state is it in,” whether automation still reports a pass.

Where it stops holding

role="presentation" / none retracts semantics and does not require state; talking about a missing state is meaningless. Static role="img" or note have no expanded/selected contract. A role="button" that fires once has no pressed; only a toggle owes that property — not every button is an incomplete widget. Readers degrade missing properties differently: some treat a combobox as a plain field, some patch nothing. Tests have to cover combinations; one vendor’s silence is not the result.

Applying it

• Before introducing a non-native role, list the states in that role’s contract, then the visuals; do not claim the role if a required state will not be supplied.
• Checkboxes, switches, accordions, tabs, and comboboxes should keep state properties on the same field as the data model; do not leave the role as a Storybook-only badge.
• After automation passes, still ask the reader “what state is this”; if it cannot answer, fix it as a missing state, not as “has a role.”
• How to check: in the inspector, filter to custom-role nodes and look for required states with values. Then ask NVDA the current state of each. Role spoken, no state word: the contract was signed halfway.

Related

• Same group: J5.10.1 Accessible names are computed from multiple sources in a fixed, overridable order · J5.10.2 Visible text and the computed accessible name can disagree · J5.10.3 State changes must be written to the accessibility tree, not only to appearance
• Nearby: J5.02 Accessibility tree and roles · J5.03 ARIA supplement
• Search terms: incomplete ARIA widget · role without state · required states