Easily confused HTML and ARIA: hidden vs aria-hidden, alert vs status

Hiding content

Name	On screen	Keyboard can reach it	Screen readers read it
`hidden`	No	No	No
`inert`	Yes	No	No
`aria-hidden="true"`	Yes	Yes, if it is focusable: never do this	No

Add a gift message

hiddenNot on screen, not reachable by keyboard, not read

Address confirmed

Payment Linen tea towel, 12.00

inertOn screen, but not reachable by keyboard and not read

Free delivery

aria-hidden="true"The icon is on screen; screen readers skip it and read the words beside it

Which to use

hidden: Content nobody should see yet, such as a closed panel.
inert: The page behind a modal you built yourself, or content shown but not usable yet.
aria-hidden="true": Decoration that repeats nearby text, such as an icon beside its label. Never on anything focusable.

Guides that decide between these (4)

Removing meaning

Name	Removes	Content still read
`role="none"`	The element’s role	Yes
`role="presentation"`	The element’s role	Yes
`aria-hidden="true"`	The element and everything in it	No
`alt=""`	The image	Nothing to read

Linen tea towel

12.00

role="none"No table, row or cell any more; its text is still read

Linen napkin

6.00

role="presentation"The same as role="none", under its older name

4.5 out of 5

aria-hidden="true"The stars and everything in them are not read; the words are

alt=""The image is decoration: nothing to read

Which to use

role="none": A table used only for layout, or markup whose role gets in the way.
role="presentation": The same as role="none", under its older name.
aria-hidden="true": Decoration that repeats nearby text.
alt="": A decorative image.

Guides that decide between these

Unavailable and unchangeable fields

Name	Focusable	Value can change	Submitted with the form
`disabled`	No	No	No
`aria-disabled="true"`	Yes	Unless your script stops it	Yes, for a native field
`readonly`	Yes	No	Yes

Coupon code

Coupons open on 1 November.

disabledCan’t be focused or changed, and isn’t submitted

aria-disabled="true"Can be focused, so it is still found; our script stops it

Order number

readonlyCan be focused and copied, not changed; it is submitted

Which to use

disabled: A control that really can’t be used now, with the reason shown nearby.
aria-disabled="true": A control people should still find and hear, such as a Submit button that explains what is missing.
readonly: A value people may read and copy but not change, such as a reference number.

Guides that decide between these

Disabled buttons that can't be found or say why

Names and descriptions

Name	Gives	Text comes from	Visible
`<label>`	Name	Its own text	Yes
`aria-labelledby`	Name	Other elements, by id	Usually
`aria-label`	Name	The attribute	No
`aria-describedby`	Description	Other elements, by id	Usually
`title`	Name only when nothing else does	The attribute	Only on mouse hover

Email

<label>Name: “Email”, from its own text

Delivery address

Postcode

aria-labelledbyName: “Delivery address”, from the heading, by id

aria-label="Search"Name: “Search”, not on screen

Password

At least 8 characters

aria-describedbyDescription: “At least 8 characters”, read after the name

title="Shop location"Name: “Shop location”, as nothing else names the iframe

Which to use

<label>: Every visible form field.
aria-labelledby: A widget or region whose name is already on screen, such as a dialog’s heading.
aria-label: A control with no visible text, such as an icon button. Include any visible words in it.
aria-describedby: Hints and error messages, read after the name.
title: Naming an <iframe>. Elsewhere, don’t rely on it.

Guides that decide between these (5)

Announcing changes

Name	Politeness	Read on a change
`role="status"`	Polite: waits	The whole message: `aria-atomic="true"` is built in
`role="alert"`	Assertive: may interrupt	The whole message: `aria-atomic="true"` is built in
`aria-live="polite"`	Polite: waits	Only what changed, unless you add `aria-atomic="true"`
`aria-live="assertive"`	Assertive: may interrupt	Only what changed, unless you add `aria-atomic="true"`
`role="log"`	Polite: waits	New entries
`role="timer"`	Off	Nothing

role="status"Polite: waits. Reads the whole message

role="alert"Assertive: may interrupt. Reads the whole message

3 left in stock

aria-live="polite"Polite: waits. Changes when you add one to the bag

aria-live="assertive"Assertive: may interrupt. Reads only the new items, and it stays a list

No questions yet

role="log"New entries, added at the end, are read

Offer ends in 4:59

role="timer"Off: not read on every tick

Which to use

role="status": Results, “Saved”, loading messages: anything that can wait.
role="alert": Errors and warnings people must act on now. Use it sparingly.
aria-live="polite": A message that can wait, where only the part that changed should be read or the element must keep its own role.
aria-live="assertive": The same, for something urgent, such as a list of errors that must stay a list. Otherwise use role="alert".
role="log": Chat messages and activity feeds, with new entries added at the end.
role="timer": A running clock or countdown, which must not be read on every tick.

Guides that decide between these (8)

Pressed, expanded, checked, selected, current

Name	Goes on	Tells people
`aria-pressed`	A button	A toggle is on or off
`aria-expanded`	The button that shows and hides content	What it controls is open or closed
`aria-checked`	Checkbox, radio, switch	It is checked, or on
`aria-selected`	Tab, option, row, cell	It is the chosen one in its set
`aria-current`	Any element	It is where you are now

aria-current="page"On “Kitchen”

Linen tea towel

aria-pressed="false"

50 by 70 cm, in natural linen.

aria-selected="true"On “Details”

aria-expanded="false"

aria-checked="true"

Which to use

aria-pressed: A button that turns something on and off, such as Mute or Bold.
aria-expanded: Disclosures, accordions and menu buttons.
aria-checked: Checkboxes, radios and switches you build yourself; native inputs need none.
aria-selected: The chosen tab, or the chosen options in a listbox or grid.
aria-current: The current page in a nav, or the current step in a process.

Guides that decide between these (4)

Link or button

Name	Does	Keys	Screen readers say
`<a href>`	Goes to another page or place	Enter	Link
`<button>`	Does something on this page	Enter and Space	Button

Linen tea towel

Read the care guide

<a href>Goes to a place: the care notes below. Enter. Said as “link”

In your bag: 0

Care: wash at 40°C, line dry.

<button>Does something here: adds to the bag. Enter and Space. Said as “button”

Which to use

<a href>: Navigation: anything that changes the URL.
<button>: Actions: open, close, submit, add to bag.

Guides that decide between these

Buttons announced as links that Space can't press

Dialogs and popovers

Name	Modal	Focus moves in	Escape closes it	What you build
`<dialog> with showModal()`	Yes	Yes	Yes	Little: a name and a close button
`role="dialog"`	Only if you make it so	Only if you move it	Only if you script it	All of it
`role="alertdialog"`	Only if you make it so	Only if you move it	Only if you script it	All of it, unless on `<dialog>`
`popover`	No	No	Yes, for `popover="auto"`	Little

Delivery address 12 Mill Lane, Leeds

<dialog>Closed. Opened with showModal().

role="dialog"Closed. Only where <dialog> can’t be used.

role="alertdialog"Closed. On a <dialog>, for a question that needs an answer.

Tea towels are 50 by 70 cm.

popover="auto"Closed. Focus stays where it was when it opens.

Which to use

<dialog> with showModal(): Any modal dialog.
role="dialog": Only where <dialog> can’t be used.
role="alertdialog": An urgent question that needs an answer, such as confirming a deletion.
popover: Non-modal menus, pickers and tips that sit over the page.

Guides that decide between these

Name	Moved through with	Screen readers expect
`<nav>`	Tab, link to link	Ordinary links in a landmark
`role="menu"`	Arrow keys, which you script	An application menu of actions

<nav>Ordinary links: Tab goes link to link. On “Shop”

Linen tea towel

role="menu"Closed. Actions in an app, never site links.

Which to use

<nav>: Site and page navigation.
role="menu": Actions in an app, like a desktop File menu. Never site navigation.

Guides that decide between these

Hover-only dropdowns, or ones that never say they are open

Name	Moved through with	When it opens	Screen readers say	What you build
`role="menu" with aria-haspopup="menu"`	Arrow keys, Home and End, which you script	Focus moves to the first item, by your script	A menu button, then the menu and each menu item	The roles, the focus and every key
`aria-expanded on a button, with no menu roles`	Tab, as on the rest of the page	Focus stays on the button; the next Tab goes in	A button, expanded or collapsed, then each button in the list	One attribute and a toggle

Which to use

role="menu" with aria-haspopup="menu": Actions in an app-like screen, where people expect a menu that works like their operating system’s.
aria-expanded on a button, with no menu roles: A few actions on a site page, or a list that holds links.

Guides that decide between these

Action menus that open silently, out of keyboard reach

Choosing from options

Name	Free text allowed	What you build
`<select>`	No	Nothing
`<datalist>`	Yes	Nothing, but it can’t be styled
`role="listbox"`	No	Keys, focus and states
`role="combobox"`	If it is editable	Keys, the popup and states

Size

<select>Free text: no. You build nothing. Now “M”

Colour

<datalist>Free text: yes; the list only suggests. It can’t be styled.

Pattern

role="listbox"Free text: no. This script adds the keys, focus and states. Now “Plain”

Ship to

role="combobox"Editable, so free text is allowed. This script adds the keys, the popup and states.

Which to use

<select>: One or more choices from a fixed list.
<datalist>: Suggestions for a field that accepts anything.
role="listbox": A list of options styled in ways <select> can’t be.
role="combobox": Autocomplete and searchable pickers.

Guides that decide between these

Required fields

Name	Browser blocks submission	Announced as required
`required`	Yes	Yes
`aria-required="true"`	No	Yes

Name

requiredThe browser stops the form until it is filled in; announced as required

Delivery speed

aria-required="true"Announced as required, but the browser sends the form anyway; our script checks it

Which to use

required: Native fields.
aria-required="true": Fields you build yourself, such as a custom radio group, with your own validation.

Guides that decide between these

Required fields marked only by colour

Sections and landmarks

Name	Landmark
`<main>`	Yes
`<aside>`	Yes, at page level
`<section>`	Only with a name
`<article>`	No

main

Linen tea towel

50 by 70 cm, in natural linen.

<main>A landmark, once per page. Drawn here with a div, as this page has its own

<aside>A landmark when it is at page level

section

Reviews

4.5 out of 5, from 12 reviews.

<section>A landmark, because aria-labelledby gives it a name: “Reviews”

article

Linen apron

Cotton straps, one size.

<article>Not a landmark: complete on its own

Which to use

<main>: The page’s main content, once.
<aside>: Related but separate content, such as a sidebar.
<section>: A part of the page on one theme, with a heading.
<article>: Something complete on its own: a post, a comment, a product card.

Guides that decide between these

Landmarks that are missing, misplaced or leave content out

Progress or meter

Name	Shows	Without a value
`<progress>`	How far a task has got	Something is happening
`<meter>`	A measurement in a known range	Not allowed

Photo of your tea towel

No photo yet

<progress>A task: 0 of 100. Starts when you upload.

New password

Strength: Very weak

<meter>A measurement from 0 to 4: now 0. It must have a value.

Which to use

<progress>: Uploads and other long tasks.
<meter>: Disk use, password strength, ratings.

Guides that decide between these

Progress bars and meters that screen readers can't read

Easily confused HTML and ARIA

Hiding content

Which to use

Removing meaning

Which to use

Unavailable and unchangeable fields

Which to use

Names and descriptions

Which to use

Announcing changes

Which to use

Pressed, expanded, checked, selected, current

Which to use

Link or button

Which to use

Dialogs and popovers

Edit address

Delete this address?

Which to use

Navigation or menu

Which to use

Action menu or disclosure

Which to use

Choosing from options

Which to use

Required fields

Which to use

Sections and landmarks

Which to use

Progress or meter

Which to use