WAI-ARIA

you can use a <span> to behave as, and be exposed just like, a link...

<span tabindex="0" role="link"
      onclick="document.location='...'"
      onkeyup="...">link</span>

example: link

...but why would you?

unless there's a very good reason, just use <a href="...">...</a>

don't do this:

<h1 role="button">heading button</h1>

otherwise the heading is no longer a heading
(e.g. AT users can't navigate to it quickly)

you can do this instead:

<h1><span role="button">heading button</span></h1>

or, in accordance with the first rule or ARIA:

<h1><button>heading button</button></h1>

example: heading button

don't do this:

<ul role="navigation">
    <li><a href="...">...</a></li>
    ...
</ul>

do this instead:

<div role="navigation">
    <ul>
        <li><a href="...">...</a></li>
        ...
    </ul>
</div>

or list is no longer a list (e.g. AT won't say "list with X items...")

example: list navigation

don't use role="presentation" or aria-hidden="true" on a visible focusable element. Otherwise, users will navigate/focus onto "nothing".

<!-- don't do this... -->

<button role="presentation">press me</button>

<button aria-hidden="true">press me</button>

<span tabindex="0" aria-hidden="true">...</span>

example: neutralised elements

<!-- don't do this... -->

<span tabindex="0" role="button">
    <span class="glyphicon glyphicon-remove"></span>
</span>

<span tabindex="0" role="button">
    <span class="glyphicon glyphicon-remove">
        <span class="...">Delete</span>
    </span>
</span>

<span tabindex="0" role="button" title="Delete">
    <span class="glyphicon glyphicon-remove"></span>
</span>

refer to WAI-ARIA 1.1 - 5.2.7. Accessible Name Calculation

<span tabindex="0" role="button" aria-label="Delete">
    <span class="glyphicon glyphicon-remove"></span>
</span>

<span tabindex="0" role="button" aria-labelledby="...">
    <span class="glyphicon glyphicon-remove"></span>
</span>
...
<span id="..." class="...">Delete</span>

refer to WAI-ARIA 1.1 - 5.2.7. Accessible Name Calculation

<p class="1" role="heading" aria-level="1">Heading 1</p>
...
<p class="h2" role="heading" aria-level="2">Heading 2</p>
...
<p class="h3" role="heading" aria-level="3">Heading 3</p>
...

example: headings

• add role="heading"
• if more than one hierarchical level, and can't be inferred from structure, add explicit aria-level

<div role="list">
    <div role="listitem">...</div>
    <div role="listitem">...</div>
    <div role="listitem">...</div>
    ...
</div>

example: list/listitem

• add role="list" and role="listitem"
• generally more complex (big markup structures that boil down to essentially "a list of things...")

<img> is identified as an image by assistive technologies, and you can provide alternative text.

<img src="..." alt="alternative text">

if you're using embedded <svg>, use ARIA to achieve the same:

<svg role="img" aria-label="alternative text"> ... </svg>

example: embedded SVG image

if your page/app uses inappropriate markup, ARIA can be used to remove semantic meaning. useful for remediation if markup cannot be changed.

<table role="presentation">
    <tr>
        <td>Layout column 1</td>
        <td>Layout column 2</td>
    </tr>
</table>

example: layout table remediation

ARIA 1.1 introduced role="none" as an alias for role="presentation" – they are equivalent (and older browsers/AT likely better off still using role="presentation")

<span class="...">Button?</span>

<div class="...">Button?</div>

<a href="#" class="...">Button?</a>

example: button

while using a link is slightly less evil, as at least it receives keyboard focus by default, it's still not correct: links are meant for navigation, not in-page actions or form submissions

<span tabindex="0" class="..." role="button">Button!</span>

<div tabindex="0" class="..." role="button">Button!</div>

<a href="#" class="..." role="button">Button!</a>

• add role="button"
• make sure it's focusable
• add handling of SPACE (and in some cases ENTER)

assuming there's a click handler:

foo.addEventListener('keyup', function(e) {
  // Space or Enter key
  if (e.key === " " || e.key === "Enter") {
    // stop default behavior (usually, scrolling)
    e.preventDefault();
    // trigger the existing click behavior
    this.click();
  }
});

you could even do it "in one go" for all your faked buttons, assuming they have the correct role="button", with querySelectorAll and attribute selectors:

var buttons = document.querySelectorAll("[role='button']");
for (var i=0; i<buttons.length; i++) {
  buttons[i].addEventListener('keyup', function(e) {
    if (e.key === " " || e.key === "Enter") {
      e.preventDefault();
      this.click();
    }
  });
}

let's assume we implement this with JavaScript to purely add a CSS classname:

<button class="...">Toggle</button>

<button class="... toggled">Toggle</button>

example: toggle

in real applications, you'll likely keep track of the state in some additional way – this is only for illustrative purposes

<button class="..." aria-pressed="false">Toggle</button>
<button class="... toggled" aria-pressed="true">Toggle</button>

foo.getAttribute("aria-pressed");
foo.setAttribute("aria-pressed", "true");
foo.setAttribute("aria-pressed", "false");

add aria-pressed and dynamically change its value

example: toggle with aria-pressed

• these are HTML attributes and must be read/written using getAttribute() / setAttribute()
• and even boolean attributes take string values

<button class="... toggled" aria-pressed="true">Toggle</button>

button.toggled { ... }
button[aria-pressed="true"] { ... }

• bonus: use CSS attribute selectors – no need for extra CSS class (this also helps debugging – easier to spot visually when ARIA roles/properties aren't correctly set)

example: toggle with aria-pressed and simplified CSS

if your actual label text changes when toggling, aria-pressed is likely not necessary (could actually be more confusing for user)

<button ...>Mute</button>

if (...) {
    this.innerHTML = "Mute";
    ...
} else {
    this.innerHTML = "Unmute";
    ...
}

example: toggle with a changing name/label and ARIA versus toggle with a changing name/label only

<span tabindex="0" class="...">Option</span>

<span tabindex="0" class="... checked">Option</span>

example: checkbox

<span tabindex="0" role="checkbox"
      aria-checked="false" class="...">Option</span>

<span tabindex="0" role="checkbox"
      aria-checked="true" class="... checked">Option</span>

• add role="checkbox"
• make sure it's focusable
• add handling of SPACE
• add aria-checked and dynamically change its value

example: checkbox with aria-checked

<span tabindex="0" class="...">Yes</span>
<span tabindex="0" class="... selected">No</span>
<span tabindex="0" class="...">Maybe</span>

example: radio button

<span tabindex="0" role="radio"
      aria-checked="false" class="...">Yes</span>
<span tabindex="0" role="radio"
      aria-checked="true" class="... selected">No</span>
<span tabindex="0" role="radio"
      aria-checked="false" class="...">Maybe</span>

• add role="radio"
• add handling of SPACE and cursor keys
• add aria-checked and dynamically change its value
• should be contained inside role="radiogroup" (cfr. <fieldset>)

example: radio button with ARIA (but note incomplete focus handling)

<button ...>More details</button>
<div class="show" ...> ... </div>

example: disclosure widget

<button ... aria-expanded="true"
    aria-controls="disclosure1">More details</button>
<div class="show" ... id="disclosure1"> ... </div>

example: disclosure widget with aria-expanded / aria-controls

<button ... aria-expanded="true"
    aria-controls="accordion1">Item 1</button>
<div class="show" ... id="accordion1"> ... </div>

<button ... aria-expanded="false"
    aria-controls="accordion2">Item 2</button>
<div class="show" ... id="accordion2"> ... </div>

<button ... aria-expanded="false"
    aria-controls="accordion3">Item 3</button>
<div class="show" ... id="accordion3"> ... </div>

example: accordion using disclosure widgets

<button>Launch...</button>
...
<div ... >
    <div>My custom dialog</div>
    ...
</div>

example: modal dialog

...but focus handling is not really correct...

• when triggered, focus should move to the dialog
• focus should be maintained inside the dialog

example: modal dialog with focus management

...but for assistive tech users, it's still not clear what is happening...

<button>Launch...</button>
...
<div role="dialog"
     aria-labelledby="modalDialogHeader"
     aria-describedby="modalDialogDescription" ... >
  <div id="modalDialogHeader">My custom dialog</div>
  <div id="modalDialogDescription">
    ... 
  </div>
  ...
</div>

example: modal dialog with focus management and ARIA

...almost perfect, but assistive tech users can still navigate out of the modal...

<div id="wrapper">
  <button>Launch...</button>
</div>
...
<div role="dialog" ...> ... </div>

function openModal() {
 document.getElementById("wrapper")
         .setAttribute("aria-hidden","true"); ...
}
function closeModal() {
 document.getElementById("wrapper")
        .removeAttribute("aria-hidden"); ...
}

example: modal dialog with aria-hidden

note: aria-hidden does not prevent regular keyboard focus!

function openModal() {
 document.getElementById("wrapper").setAttribute("inert","");
 ...
}
function closeModal() {
 document.getElementById("wrapper").removeAttribute("inert");
 ...
}

example: modal dialog with inert

note: inert does hide elements from accessibility tree and remove behavior such as keyboard focusability. however, not natively supported yet – use the inert polyfill

<button>Launch...</button>
...
<div role="dialog" aria-modal="true"
     aria-labelledby="modalDialogHeader"
     aria-describedby="modalDialogDescription" ... >
  <div id="modalDialogHeader">My custom dialog</div>
  <div id="modalDialogDescription">
    ... 
  </div>
  ...
</div>

example: modal dialog with aria-modal (new in ARIA 1.1)

...but you still need to do the focus management yourself...

see also: Scott O'Hara: The current state of modal dialog accessibility

	<span tabindex="-1" role="radio"
		  aria-checked="false" class="...">Yes</span>
	<span tabindex="0" role="radio"
		  aria-checked="true" class="... selected">No</span>
	<span tabindex="-1" role="radio"
		  aria-checked="false" class="...">Maybe</span>
	

only one radio button inside the group has focus. changing the selection using CURSOR keys, dynamically changes tabindex, aria-checked and sets focus() on the newly selected radio button

example: ARIA Authoring Practices Guide - Radio Group Using Roving tabindex

<div id="output"></div>

var o = document.getElementById("output");
o.innerHTML = "Surprise!"; // show the notification

example: notification as result of button press

but how can AT users be made aware of the notification / content change?

one way to notify users of assistive technologies of new content (a new element added to the page, made visible, a change in text) is to move focus() programmatically to it

<div id="output" tabindex="-1"></div>

var o = document.getElementById("output");
o.innerHTML = "Surprise!"; // show the notification
o.focus(); // move focus to the notification

but this is not always possible, as it would interrupt the user's current actions...

example: notification via focus() and a more problematic example simulating a long-running function.

<div id="output" aria-live="polite"></div>

var o = document.getElementById("output");
o.innerHTML = "Surprise!"; // show the notification

example: notification via aria-live

bonus points: set aria-disabled="true" on the control, and optionally aria-busy="true" on the notification / section of the page that is getting updated. see notification via aria-live, with aria-busy and aria-disabled

<span role="status">
    some form of status bar message...
</span>

example: status bar

<span role="alert">
    an alert message (no user interaction)
</span>

example: alert

// create a new div element 
var newDiv = document.createElement("div");

// set aria-live property
newDiv.setAttribute("aria-live", "polite");

// and give it some content 
var newContent = document.createTextNode("Surprise!"); 

// add the text node to the newly created div
newDiv.appendChild(newContent);

// add the new div to the page
document.body.appendChild(newDiv);

// ... WON'T ACTUALLY WORK

<div role="tablist" ...>
  <div role="tab" aria-controls="panel1"
       aria-selected="true"...>Tab 1</div>
  <div role="tab" aria-controls="panel2" ...>Tab 2</div>
  <div role="tab" aria-controls="panel3" ...>Tab 2</div>
</div>

<div role="tabpanel" id="panel1">...</div>
<div role="tabpanel" id="panel2" aria-hidden="true">...</div>
<div role="tabpanel" id="panel3" aria-hidden="true">...</div>

example: ARIA Authoring Practices Guide - Tabs with Automatic Activation

variations: Marco Zehe: Advanced ARIA tip #1: Tabs in web apps

not appropriate if you're just marking up a site navigation...

<div role="menubar">
  <div role="menuitem" ...>...</div>
  <div role="menu">
    <div role="menuitem" ...>...</div>
    <div role="menuitem" ...>...</div>
    <div role="menuitem" ...>...</div>
    ...
  </div>
  ...
</div>

example: ARIA Authoring Practices Guide - Navigation Menubar

most suitable for "application-like" web-app menus, not for general "website navigation"

Marco Zehe: WAI-ARIA menus, and why you should generally avoid using them