Skip to content
Tutorials Center
My learning

Topics

Lesson 46 of 58 ยท Quality

Accessibility in Bootstrap

Build accessible Bootstrap pages: semantic markup, the ARIA attributes components need, modal focus, visually-hidden text, skip links, contrast and reduced motion.

A page is accessible when people can use it whatever their abilities and tools: with a keyboard instead of a mouse, with a screen reader, with low vision or color blindness, with a slow connection or with motion turned off. Bootstrap helps a great deal. Its components follow accessibility patterns, its colors are chosen with contrast in mind, and its JavaScript plugins manage keyboard behavior and focus. But Bootstrap cannot see your content. Classes cannot make a <div> into a button or write a missing label, so a lot of the work stays with you.

This lesson covers what Bootstrap already does, what you must add, and how to check the result.

Start with the right element

The most effective accessibility step costs nothing: use the HTML element that matches the job. Browsers give native elements keyboard behavior, focus and meaning for free.

flowchart TD
  Q{"What does it do?"} -->|"Runs an action on this page"| B["button"]
  Q -->|"Goes to another page or place"| A["a href"]
  Q -->|"Collects input"| I["input, select, textarea<br/>with a label"]
  Q -->|"Groups the main content"| M["main, nav, header, footer, section"]
  B --> C["class btn ..."]
  A --> C2["class btn ... allowed"]

Pick the element by behavior; then add Bootstrap classes for looks.

  • Use <button class="btn btn-primary" type="button"> for actions. A <div class="btn"> with a click handler is not focusable, ignores Enter and Space, and is announced as plain text.
  • Use <a class="btn btn-outline-primary" href="/pricing"> when the control navigates. Do not use <a href="#"> for actions.
  • Use landmark elements: <header>, <nav>, <main> (one per page), <footer>. Screen reader users jump between landmarks.
  • Keep heading levels in order (h1 then h2 then h3). If a heading looks too big, keep the right level and change the look with .h5 or .fs-5, which is exactly what those classes are for.
  • Set lang on <html> so screen readers choose the right voice.

Disabled links. .disabled on an <a> only changes the look; it does not stop keyboard activation. Bootstrap's documentation recommends also adding aria-disabled="true" and tabindex="-1" to a disabled link. Better still, use a real <button disabled> when the control is an action.

Labels and forms

Every form control needs an accessible name. The simplest way is a visible <label> connected with for and id. A placeholder is not a label: it disappears when you type and often has poor contrast.

Bootstrap's form classes (form-label, form-control, form-text) are all designed around this. Connect help text and errors with aria-describedby so screen readers read them with the field:

A labelled field with help and an error

Notice four habits: a real label, aria-describedby pointing to the help and the error, aria-invalid toggled with the visual is-invalid state, and focus moved to the field that needs fixing. The status message sits in an aria-live="polite" region so a screen reader announces it when the text changes.

ARIA in Bootstrap components

ARIA attributes add meaning where HTML alone cannot express it. A rule worth memorizing: no ARIA is better than bad ARIA. Use it only to describe what a component really does. Bootstrap's JavaScript keeps some attributes up to date for you, and you must write others.

Component You must write Bootstrap updates
Collapse / accordion button aria-expanded, aria-controls aria-expanded when toggled
Navbar toggler aria-label="Toggle navigation", aria-expanded, aria-controls aria-expanded
Close button (btn-close) aria-label="Close" (it has no text) none
Modal aria-labelledby pointing to the title, tabindex="-1" aria-modal, role="dialog", removes aria-hidden while open
Tabs role="tablist", role="tab", role="tabpanel", aria-controls, aria-labelledby aria-selected, roving tabindex, arrow-key navigation
Dropdown toggle the button with aria-expanded="false" aria-expanded
Progress bar role="progressbar", aria-valuenow, aria-valuemin, aria-valuemax, a label none
Spinner role="status" and visually hidden text none
Alert shown dynamically role="alert" none
Toast role="alert" (urgent) or role="status" (polite), aria-live, aria-atomic="true" none
Carousel aria-label on controls and indicators, a pause option aria-current on the active indicator

Two details trip people most often. Icon-only buttons need a name, because a screen reader cannot read an icon:

HTML
<button type="button" class="btn-close" aria-label="Close"></button>
<button type="button" class="btn btn-outline-secondary" aria-label="Search">
  <svg aria-hidden="true" width="16" height="16" viewBox="0 0 16 16"><circle cx="7" cy="7" r="5" fill="none" stroke="currentColor" stroke-width="2"/><path d="M11 11l4 4" stroke="currentColor" stroke-width="2"/></svg>
</button>

And decorative images or icons should be hidden from assistive technology with aria-hidden="true" (or alt="" on an <img>), so they are not read aloud as noise.

Focus management in modals

A modal is where focus matters most. When a dialog opens, a keyboard user must land inside it, must not be able to tab out into the page behind, and must return to where they were when it closes. Bootstrap's modal does all three:

  1. On open it moves focus into the modal and sets aria-modal="true".
  2. It traps focus: Tab and Shift+Tab cycle through the modal's focusable elements only.
  3. Escape closes it (unless you set data-bs-keyboard="false").
  4. When it closes after being opened by a data-attribute button, focus goes back to that button.

You supply the pieces Bootstrap cannot guess: the title that names the dialog (aria-labelledby), and a sensible field to start on (see below). Try it with the keyboard: click once inside the preview, press Tab until the button is focused, press Enter, and then Tab around the dialog.

Modal focus: in, trapped, and back

By default Bootstrap focuses the dialog itself. The HTML autofocus attribute has no effect inside a Bootstrap modal, so the script above focuses the input in the shown.bs.modal handler, which gives the dialog a useful starting point. For a destructive confirmation (delete, discard) it is often kinder to start on the Cancel button instead.

Sometimes content is meant for assistive technology only: the word "Loading" next to a spinner, the meaning of an icon, a heading that names a region. Bootstrap's .visually-hidden class hides an element visually while leaving it in the accessibility tree. This is different from display: none or the hidden attribute, which remove it for everyone.

HTML
<button class="btn btn-primary" type="button" disabled>
  <span class="spinner-border spinner-border-sm" aria-hidden="true"></span>
  <span role="status">Saving...</span>
</button>

<a href="/cart"><i class="icon-cart" aria-hidden="true"></i> <span class="visually-hidden">Shopping cart</span></a>

.visually-hidden-focusable is a variant that reveals the element when it receives keyboard focus. That is exactly what a skip link needs. A skip link is the first focusable element on the page; it lets keyboard users jump past a long navigation straight to the content, instead of tabbing through every menu item on every page.

A skip link that appears on focus

The target needs tabindex="-1" so that some browsers can move focus to it. Put the skip link first in <body>.

Color and contrast

Bootstrap's palette was chosen for contrast, but only for the combinations it uses. Bootstrap pairs each background with a suitable text color: white on primary, success and danger, black on warning and info. The trouble starts when you use a theme color as text on white.

JS Contrast of theme colors as text on white

Press Run (or Ctrl + Enter) to see the console output here.

No output.

text-warning and text-info on a white page are nearly unreadable for many people (about 1.6:1 and 2:1). Prefer text-warning-emphasis or a colored alert with alert-warning. In dark mode, the emphasis variants adapt automatically, as covered in Color Modes and Dark Mode.

Also remember:

  • Never use color alone. A red border is not enough for an error; add a message. Bootstrap's links are underlined by default for this reason; think twice before removing underlines with link-underline-opacity-0 in running text.
  • Do not remove focus outlines. Bootstrap draws a visible focus ring on buttons and fields. If you restyle them, give the replacement at least equal visibility. The .focus-ring helper adds a ring to your own elements.
  • Test your custom colors, as in the custom theme lesson, including dark mode.

Respect reduced motion

Some people get dizzy or distracted by animation, and set "reduce motion" in their operating system. Browsers pass this on through the prefers-reduced-motion media query. Bootstrap's own components already use it: when the preference is reduce, transitions are switched off on modals, carousels, collapses and form controls, and spinners slow down. The compile-time switch is $enable-reduced-motion (on by default).

For your own animations, do the same. Make the motion the exception:

Animation that respects reduced motion

The same applies to autoplay: a carousel that rotates by itself should offer a pause control, and moving content should stop after five seconds or be stoppable.

Testing accessibility

Automated tools find roughly a third of the problems, so combine methods:

  1. Keyboard only. Unplug the mouse. Can you reach everything with Tab, see where focus is, open and close every component, and never get trapped?
  2. Zoom and resize. Zoom to 200% and test a narrow window. Bootstrap's responsive layout should reflow without sideways scrolling.
  3. Automated checks. Browser tools such as Lighthouse and axe catch missing labels, low contrast and invalid ARIA.
  4. A screen reader. Try NVDA (Windows), VoiceOver (macOS and iOS) or TalkBack (Android) on your key flows, even for ten minutes.
  5. Reduce motion and dark mode switched on.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A designer builds a clickable control as <div class="btn btn-primary" onclick="save()">. What is the main accessibility problem?

    A native <button> provides focus, keyboard activation and the right role. A div with a click handler provides none of these.
  2. 2. What does .visually-hidden do?

    It clips the element to a tiny area so sighted users do not see it, while assistive technology still reads it.
  3. 3. Which attribute gives an icon-only .btn-close its accessible name?

    The close button has no text. aria-label supplies the name that screen readers announce.
  4. 4. What happens to focus when a Bootstrap modal opened from a button is closed?

    Bootstrap traps focus inside an open modal and returns it to the trigger on close, so keyboard users keep their place.
  5. 5. Why is text-warning on a white page a poor choice?

    Bright yellow on white is hard to read. Use text-warning-emphasis or an alert-warning box instead.

Summary

  • Choose elements by behavior: button for actions, a for navigation, labelled inputs for data, landmarks for structure, headings in order.
  • Give every control an accessible name, connect help and errors with aria-describedby, and mark invalid fields with aria-invalid.
  • Some ARIA attributes you must write (aria-label on btn-close, aria-labelledby on a modal); Bootstrap's scripts update others such as aria-expanded and aria-selected.
  • Bootstrap's modal moves focus in, traps it, closes on Escape and returns focus to the trigger.
  • .visually-hidden and .visually-hidden-focusable serve screen reader text and skip links.
  • Check contrast (4.5:1 for normal text), do not rely on color alone and keep focus visible.
  • Honor prefers-reduced-motion in your own animations, and test with keyboard, zoom, tools and a screen reader.

Next lesson: Performance and Best Practices.