HTML and ARIA reference

The root of the page. Give it a lang attribute for the page’s main language, so screen readers use the right voice and pronunciation and browsers pick the right fonts and hyphenation.

The page’s name, shown in the tab and read first when the page loads. Make each one unique and put the specific part first: “Checkout – Fern & Fold”.

Page metadata: the character set, the viewport, a description. Never set maximum-scale=1 or user-scalable=no in the viewport: it stops people zooming on mobile.

Introductory content, such as the site’s logo and navigation. It is the banner landmark only when it is not inside <article>, <aside>, <main>, <nav> or <section>; there it is just a header for that part.

A major block of navigation links. With more than one on a page, name each with aria-label (“Main”, “Footer”) and leave the word “navigation” out: the screen reader says it.

Wraps a search or filter form and makes it a search landmark, without adding role="search" to the form.

The page’s main content, once per page (others must be hidden). Screen reader users jump straight to it, and a skip link can point to it.

A thematic section of the page, normally with a heading. It becomes a region landmark only when it has a name, such as aria-labelledby pointing to that heading.

A self-contained piece that would make sense on its own: a post, a comment, a product card. Start it with a heading.

Headings, ranked by level. Screen reader users list them and jump between them, so give the page one <h1>, don’t skip levels going down, and choose the level by structure, not size.

Content related to the page but separate from its main content, such as a sidebar. It is a complementary landmark; name it when there is more than one.

Closing content, such as copyright, contact and policy links. It is the contentinfo landmark only when it is not inside <article>, <aside>, <main>, <nav> or <section>.

An unordered list of items. Outside <nav>, Safari with VoiceOver drops the list role when list-style: none is set; add role="list" if the count matters there.

An ordered list, where the sequence matters, such as steps. Screen readers say how many items there are and which one you are on.

An item in <ol>, <ul> or <menu>. It must be a direct child of one of them, or it is not counted as part of the list.

A description list of term and description pairs, such as specifications or a glossary. Keep only <dt>, <dd> and wrapping <div> elements directly inside it.

Self-contained content such as an image, chart or code sample, usually with a <figcaption> that names it. The caption does not replace an image’s alt.

The caption of its <figure>, as its first or last child. It gives the figure its accessible name.

A link to another page or place: a link only with an href, and reached with Tab and Enter. Its text must say where it goes; for an action on the page, use <button>.

An abbreviation. Its title attribute is not reliably read or shown on touch screens, so spell the term out in the text the first time it appears.

Ruby annotation: small text above or beside characters, such as furigana showing how kanji are read. Screen readers vary in how they read it, often saying both base and ruby.

Text highlighted for reference, such as search matches. Many screen readers don’t announce it, so don’t rely on the highlight alone to convey something.

Text that is no longer accurate or relevant, such as an old price. Screen readers often don’t say it is struck through, so add words like “was” if it matters.

Text removed from the document, for a record of edits. Most screen readers don’t announce it by default, so say in words what changed if it matters.

Text added to the document, for a record of edits. Most screen readers don’t announce it by default.

An image. alt is required: describe what the image tells the reader, or use alt="" for a decorative image so screen readers skip it. Without alt, many screen readers read the file name.

A clickable area in an image map. With an href it is a link, and its alt is the link text, so it is required.

An inline SVG drawing. For a meaningful image, add role="img" and a name with aria-label or <title>; for decoration, add aria-hidden="true".

A surface drawn on with script. What is drawn is invisible to assistive technology, so give the same information as text, in the fallback content or nearby.

Embeds another page, such as a map or a video player. Give it a title that says what it contains, so screen reader users know whether to go in.

A video player. Add controls, captions with <track>, and an audio description or transcript; don’t autoplay with sound.

An audio player. Add controls and offer a transcript; audio that plays on its own for more than three seconds needs a way to stop it.

How captions and audio descriptions reach a <video>: a WebVTT file whose kind says which it is. Prerecorded video with sound needs captions (WCAG 1.2.2).

A data table, where screen readers announce each cell with its headers. Use it for data in rows and columns, not for layout, and give it a <caption>.

The title of a table, as its first child. It names the table, so screen reader users know what it holds before reading cells.

A header cell for its column or row. Set scope="col" or scope="row" so its direction is clear, and use headers for complex tables.

A data cell. Screen readers announce it with its row and column headers, worked out from <th> elements or the headers attribute.

A form that submits its fields. Submitting with Enter works only inside one. It is a form landmark only when it has a name.

Groups related fields, such as a set of radio buttons or an address, under the question in its <legend>, which screen readers announce with the fields.

The caption of a <fieldset>, as its first child. Keep it short: some screen readers repeat it on every field in the group.

The visible name of a form field, tied to it with for and the field’s id, or by wrapping it. It is read when the field gets focus, and clicking it focuses the field.

A form field whose type sets what it is: text, email, checkbox, radio, number, date and more. Every one needs a label, and the right type and autocomplete give people the right keyboard and autofill.

A multi-line text field. Like any field it needs a label; don’t stop it being resized if people may need more room.

A list of options to choose from, with keyboard and screen reader support built in. Give it a label, and don’t submit or navigate when the selection changes.

Groups related options in a <select> under a label, which many screen readers announce with the options.

Suggestions for an <input>, tied to it with the input’s list attribute; people can still type anything. Screen reader support for the suggestions varies between browsers.

A button that does something on the page. It is focusable and works with Enter and Space for free. Inside a form it submits by default, so set type="button" for other actions.

The result of a calculation or user action, such as a total. It is a status live region, so screen readers may announce changes to it.

How far a task has got, such as an upload. Give it a label; without a value it shows that something is happening but not how much.

A measurement within a known range, such as password strength, which screen readers announce with its value. Give it a label, and say the level in text too, not by colour alone (WCAG 1.4.1). For task progress, use <progress>.

A disclosure widget that shows and hides its content when its <summary> is pressed, with keyboard and screen reader support built in. Several with the same name open one at a time.

The always-visible label of a <details> that opens and closes it. Most browsers expose it as a button-like control with its expanded state, though the exact role varies; don’t put other interactive elements inside it.

A dialog box. Opened with showModal(), it is modal: it moves focus inside, makes the rest of the page inert and closes with Esc. Give it a name from its heading.

Sets the language of the element's content, so screen readers pronounce it with the right voice and browsers hyphenate and translate it correctly. Set it on <html> for the page (WCAG 3.1.1) and on any passage in another language (WCAG 3.1.2).

Sets the text direction. Use rtl for Arabic, Hebrew and other right-to-left scripts, and auto for user-generated text whose direction is not known in advance.

Advisory text shown as a tooltip on mouse hover. Do not rely on it: keyboard and touch users never see it, and screen readers read it inconsistently. Its one dependable use is naming an <iframe>.

Hides the element from everyone: it is not shown, not focusable and not read by screen readers. With until-found, the content stays findable with the browser's find in page and opens when found.

Makes an element and everything in it unreachable: it cannot be focused, clicked or found by a screen reader, though it stays visible. Use it on the page behind a custom modal or on content that is shown but not yet usable.

Controls whether an element takes keyboard focus. 0 adds it to the Tab order in source order, -1 lets scripts focus it without putting it in the Tab order. Never use a positive number: it jumps the element ahead of everything else.

Moves focus to the element when the page or dialog opens. Use it only where people expect to start, such as the first field of a dialog; elsewhere it skips content a screen reader user has not heard yet.

Assigns a keyboard shortcut to an element. Avoid it: the keys clash with screen reader, browser and system shortcuts, the modifier differs between browsers, and nothing tells people the shortcut exists.

Makes the element's content editable in place. The browser exposes it as an editable text area, but it has no name: give it a label with aria-labelledby or aria-label, and aria-multiline where it takes several lines.

Chooses which on-screen keyboard to show, such as a number pad for a one-time code, without the validation and spin buttons of type="number".

Gives an element one of the ARIA roles, which tells assistive technology what it is. It changes only what is announced, never behaviour, so a native element that already has the role is better (see the ARIA roles below).

Turns an element into a popover shown in the top layer, opened by a button with popovertarget. An auto popover closes with Escape and when you click outside it; popover does not trap focus or make the page inert, so it is not a modal dialog.

Makes a <meta> act like an HTTP header. Avoid http-equiv="refresh" with a delay: a page that reloads or redirects on its own takes people away before they finish reading (WCAG 2.2.1).

The URL a link goes to. An <a> without href is not a link and cannot be focused; never use href="#" or javascript: to make a link act as a button.

Where to open the link. _blank opens a new tab or window, which disorients people and breaks the Back button, so use it sparingly and say so in the link text.

The text alternative for an image: what it conveys in this context (WCAG 1.1.1). Use alt="" for a purely decorative image so screen readers skip it; leaving alt out makes many read the file name.

Shows the browser's own playback controls, which work with the keyboard and screen readers. Keep them unless you build a custom player that is just as accessible.

Starts playback as soon as it can. Sound that plays on its own for more than 3 seconds needs a way to pause or mute it (WCAG 1.4.2), and moving video needs a pause control (WCAG 2.2.2); better not to autoplay at all.

Starts the media with its sound off. Browsers allow muted video to autoplay; it still needs a pause control if it moves.

Restarts the media when it ends. Looping video that starts on its own and moves for more than 5 seconds needs a way to pause it (WCAG 2.2.2).

What a text track is. Use captions for dialogue plus sound effects for deaf viewers (WCAG 1.2.2), subtitles for when the sound can be heard but not understood, such as a translation, and descriptions for text audio description.

The language of a text track, required for subtitles. Pair it with a label that names the language in words people recognise.

Turns this text track on by default. Put it on the captions in the page's language, so captions are there without hunting for the setting.

Says whether a header cell labels its column, row or group of them, so screen readers read the right header with each data cell.

A list of header cell ids that apply to this cell, for tables too complex for scope. Prefer simplifying the table first.

A short form of a header cell's text, for when the full header is long. Screen reader support is patchy, so keep the visible header itself reasonably short.

How many columns a cell spans. Screen readers announce the span, but merged cells make tables harder to follow; split complex tables where you can.

How many rows a cell spans. As with colspan, keep merged cells to a minimum so people can follow the table cell by cell.

Ties a <label> to the control with that id, which gives the control its accessible name and makes clicking the label focus or toggle the control.

Names an <optgroup>, which many screen readers announce with its options, or a <track>, shown in the player’s captions menu, where the language should be named in words people recognise.

Groups radio buttons, so the arrow keys move between them and screen readers say how many there are. It is not an accessible name: each control still needs a label.

On <input>, the kind of control (text, email, checkbox, date…), which sets its role, keyboard and validation. On <button>, submit, reset or button: set type="button" on any button that does not submit a form.

Says what personal data a field collects, so browsers and password managers can fill it in. Fields about the user need the matching token (WCAG 1.3.5), which also saves typing for people with motor and memory impairments.

Sample text shown in an empty field. It is not a label: it disappears as soon as people type, is often low contrast, and is not read reliably. Put instructions in a visible label or hint.

Makes a field mandatory: the browser blocks submission and screen readers announce the field as required. Also show that it is required in the visible label, not with colour or an unexplained asterisk alone.

Disables a form control: it is removed from the Tab order, cannot be used and is not submitted. Because it cannot be focused, people may not find it or learn why it is off; aria-disabled keeps it focusable instead.

Makes a field's value unchangeable while keeping it focusable, readable and submitted. Unlike disabled, people can still reach it and select its text.

Ties a field to a <datalist>, so the browser offers suggestions and handles their keys itself, while people can still type anything. Simpler than a scripted combobox when the list needn’t be styled.

Shows the content of a <details> element, or shows a <dialog>. Open a dialog with showModal() instead of setting open, so it is modal and focus moves into it.

Makes a button open, close or toggle the popover with that id. The browser exposes the button's expanded state and, if focus is inside the popover when it closes, moves focus back to where it was before (usually the button).

Opens or closes a <dialog> or popover from a button with no script. show-modal opens a dialog as showModal() does: modal, with focus moved inside and the page behind inert.

Names, by id, the dialog or popover a button’s command acts on, so the button works without a script, even before scripts have loaded.

Something that performs an action when pressed. With the role you must add tabindex="0" and make Enter and Space activate it yourself. Prefer <button>, which does all of that already.

A reference that takes people somewhere when activated. With the role you must add focus and Enter yourself, and lose the browser’s link features. Prefer <a href>.

A box that is checked, unchecked or, with aria-checked="mixed", partly checked. Requires aria-checked, focus and Space to toggle it. Prefer <input type="checkbox">.

One option in a set where only one can be checked. Requires aria-checked, sits in a radiogroup, and the arrow keys move and check within the set. Prefer <input type="radio">.

An on/off control, such as a setting that takes effect at once. Requires aria-checked ("true" or "false"); a <button> with the role is the simplest base.

A selectable item in a listbox. It must be owned by a listbox (or a group in one), and ARIA 1.2 requires aria-selected on it: true on selected options, false on the rest.

An action in a menu or menubar. It must be inside a menu, menubar or a group within one, and the menu moves focus between items with the arrow keys.

A menu item that can be checked or unchecked, such as “Show grid”. Requires aria-checked; activating it toggles the state and usually leaves the menu open.

One of a set of menu items where only one can be checked, such as a sort order. Requires aria-checked; group the set with role="group" or separators.

One label in a tablist, which shows its tabpanel. Set aria-selected on it and aria-controls to its panel; the arrow keys move between tabs.

The content a tab shows. Name it with aria-labelledby pointing to its tab, and hide the panels that aren’t shown.

A field for free text; with aria-multiline="true", one that takes several lines. Prefer <input> or <textarea>; a contenteditable element needs the role and a name.

A text field for search terms. Prefer <input type="search">, which has the role, and put the search form in a search landmark.

Picks a value from a range by moving a thumb. Requires aria-valuenow and a name, and arrow keys to change the value. Prefer <input type="range">.

A field holding a number that the Up and Down arrows step through. Set aria-valuenow when it has a value. Prefer <input type="number"> for real quantities.

Shows how far a task has got. Give it a name and aria-valuenow (with aria-valuemin and aria-valuemax); leave out aria-valuenow when the progress is unknown. Prefer <progress>.

An item in a tree. One with children takes aria-expanded; it must be owned by a tree or by a group inside one.

A cell in a grid or treegrid, which can take focus or be edited. It must be owned by a row in a grid; the arrow keys move between cells.

A field that pops up a listbox, grid, tree or dialog of suggestions. Requires aria-expanded and, in ARIA 1.2, aria-controls pointing at the popup; use aria-activedescendant for the highlighted option.

A list of options to choose one or, with aria-multiselectable, several. It needs a name and options; the arrow keys move the selection. Prefer <select> where it fits.

A list of actions or settings, like an application’s menu. It is not for site navigation links: screen readers switch to menu mode and expect arrow-key behaviour.

A row of menus that usually stays visible, as in a desktop application. Left and Right move between its items; like menu, it is not for a website’s navigation.

Groups a set of radio buttons under one name. Give it a name; with native radios, a <fieldset> and <legend> do the same job.

The container of a set of tabs. It must own the tabs; give it a name, and aria-orientation="vertical" when the tabs are stacked.

A list of items that can be expanded and collapsed, such as folders. It needs a name and treeitems; the arrow keys move, open and close items.

A grid whose rows can be expanded and collapsed like a tree, such as an email thread list. Rows take aria-expanded and aria-level.

A table of cells navigated with the arrow keys, such as a calendar or a spreadsheet. Only one cell is in the Tab order; use a plain table when nothing in it is interactive.

A heading for a section, which screen reader users jump between. Requires aria-level; browsers usually treat a missing level as 2. Prefer <h1>–<h6>.

A list of items, announced with its count. It must contain listitems. Prefer <ul> or <ol>; add the role back only where CSS such as list-style: none drops it in Safari.

One item in a list; it must be contained in or owned by a list. Prefer <li>.

Data in rows and columns that isn’t interactive. Prefer <table>; the role is for tables built from other elements, and needs rows and cells inside.

A row of cells in a table, grid or treegrid; it must be inside one, or in a rowgroup within one. Prefer <tr>.

A group of rows, such as a table’s head or body. Prefer <thead>, <tbody> and <tfoot>.

The header of a column, read with each cell under it. Prefer <th scope="col">; in a sortable table it takes aria-sort.

The header of a row, read with each cell in it. Prefer <th scope="row">.

A cell in a static table, owned by a row. Prefer <td>; for a layout built with CSS grid, the roles restore the table that display: grid can hide.

One image, possibly made of several parts, such as an inline SVG, emoji or icon font. It needs aria-label or aria-labelledby; its children are not read.

A self-contained illustration, chart or code sample, usually with a caption. Prefer <figure> with <figcaption>.

A set of related elements that isn’t a landmark, such as related fields or the options in a menu section. Give it a name when the grouping matters. Prefer <fieldset> for form fields.

A set of controls, such as text formatting buttons. Give it a name when there is more than one; only one control is in the Tab order and the arrow keys move between them.

A divider between sections or menu groups. Prefer <hr>. A focusable separator is a widget that resizes panes, and then needs aria-valuenow.

A short description that appears when its owner has focus or the pointer. It never takes focus itself; the owner points to it with aria-describedby, and Escape hides it.

A note that is parenthetical or ancillary to the main content, such as a tip beside a step.

A self-contained piece, such as a post, a comment or a product card. Prefer <article>.

A scrolling list of articles that loads more as people reach the end. Its articles take aria-posinset and aria-setsize, and the feed sets aria-busy while it adds them.

A value within a known range, such as disk use or password strength; not progress. Requires aria-valuenow and a name. Prefer <meter>.

Removes an element’s own role, keeping its content, such as a layout table. Ignored on focusable elements and on those with global ARIA attributes. Same as presentation.

The older name for none: removes an element’s role but keeps its content. Ignored on focusable elements and on those with global ARIA; an <img alt=""> already has it.

Tells screen readers to pass every key to the page, turning off their reading keys. Almost never right: only for a widget that handles all keys itself and needs no reading.

The site-wide header, with the logo and main navigation; one per page. Prefer a <header> that isn’t inside article, aside, main, nav or section.

A set of links for moving around the site or page. Name each one when there is more than one, without the word “navigation”. Prefer <nav>.

The region that holds the site or page search. Prefer <search>; put the role on the <form> where older browsers matter.

The page’s main content, which a skip link and screen reader shortcuts jump to; one visible per page. Prefer <main>.

A section important enough to be listed among the landmarks. It is a landmark only when it has a name; a <section> with aria-labelledby gets the role.

A region holding a form. It is a landmark only when it has a name, so name the forms people need to find. Prefer <form> with aria-label or aria-labelledby.

Content that supports the main content but makes sense on its own, such as related links. Name it when there is more than one. Prefer <aside>.

The site-wide footer, with copyright and policy links; one per page. Prefer a <footer> that isn’t inside article, aside, main, nav or section.