Skip to main content

Getting started

Accessibility

What you get for free from native elements, what the theme adds, and the few things you still have to do yourself.

Native semantics

Stock Bootstrap builds its interactive parts out of <div>s and bolts the semantics on with ARIA and JavaScript. rb-bootstrap starts from the element that already has the right role. The role, the name, the state and the keyboard handling come from the browser.

PatternElementWhat the browser provides
Collapse, accordion, dropdown<details> / <summary>Button role on the summary, expanded/collapsed state, Space and Enter, exclusive groups via name
Modal<dialog>Dialog role, Escape, top layer, ::backdrop; inert page and focus trap with command="show-modal"
Alert dismiss<dialog open> + <form method="dialog">The close button is a real submit button; the alert leaves the tree when closed
Tabs, pillsRadio inputs + labelsArrow-key selection, one tab stop for the whole list, checked state
Navbar toggle, button toggleCheckbox + labelSpace toggles, checked state announced
Offcanvas, popover, toastPopover APITop layer, light-dismiss and Escape (auto), autofocus honoured on open
CarouselScroll-snap trackNative scrolling, arrow keys when the track has focus, generated scroll buttons where supported
Form validation:user-invalid / :user-validConstraint validation, native error bubbles, no premature red fields

You still own the labels. Give every dialog an aria-labelledby, every icon-only button an aria-label, and every form control a <label>. See No JavaScript for the markup of each component.

Keyboard behaviour

Nothing here is scripted. These are the keys each component answers to.

ComponentKeysNotes
Collapse, AccordionTab to the summary; Space or Enter togglesAn exclusive accordion closes the open item when another opens
Dropdown (<details>)Space or Enter opens; Tab walks the items; Space or Enter on the summary closesNo Escape. Use the popover variant for Escape and light-dismiss
Dropdown (popover)Enter opens; Tab walks the items; Escape closesFocus returns to the invoking button
TabsTab lands on the selected tab; Left/Right or Up/Down move selection and switch the paneThe radio group is one tab stop, matching the WAI-ARIA tabs pattern
Navbar togglerSpace toggles the menuThe hidden checkbox keeps focus; the label shows the ring
ModalEscape closes; Tab cycles the controlsFocus is trapped and the page is inert only with command="show-modal"
OffcanvasEscape closespopover="manual" turns Escape off
PopoverEnter on the trigger opens; Escape closesPut autofocus on the first control inside
ToastTab to the close button; Enter or Spacepopover="manual", so Escape does not dismiss it
TooltipShows on :focus-visibleOnly focusable elements get tooltips. Keep the host a button, link or input
CarouselArrow keys scroll the track when it has focus; indicator links are tab stopsAdd tabindex="0" to .carousel-inner if nothing inside it is focusable
Button toggleSpace toggles a checkbox; arrows move within a radio group.btn-check is Bootstrap's own markup
Alert dismissEnter or Space on the close buttonIt is a submit button in a method="dialog" form

Try the radio tabs. Tab into the list, then use the arrow keys.

Six matches. Main event: steel cage.
Winner by pinfall at 14:22.
Billed height 6'4". Billed weight 275 lb.
HTML
<div class="tabs">
  <ul class="nav nav-tabs" role="tablist">
    <li class="nav-item">
      <input type="radio" class="nav-check" name="a11y-tabs" id="a11y-tab-card" checked />
      <label class="nav-link" for="a11y-tab-card">Card</label>
    </li>
    <li class="nav-item">
      <input type="radio" class="nav-check" name="a11y-tabs" id="a11y-tab-results" />
      <label class="nav-link" for="a11y-tab-results">Results</label>
    </li>
    <li class="nav-item">
      <input type="radio" class="nav-check" name="a11y-tabs" id="a11y-tab-tape" />
      <label class="nav-link" for="a11y-tab-tape">Tale of the tape</label>
    </li>
  </ul>
  <div class="tab-content pt-3">
    <div class="tab-pane">Six matches. Main event: steel cage.</div>
    <div class="tab-pane">Winner by pinfall at 14:22.</div>
    <div class="tab-pane">Billed height 6'4". Billed weight 275 lb.</div>
  </div>
</div>

Focus rings

The focus ring is title-belt gold at 40 % opacity, 0.25 rem wide. It is defined once on the root and every control reads it: buttons, inputs, selects, checks, the .focus-ring helper, and the hidden radio and checkbox inputs that drive tabs and the navbar toggle (those forward the ring to their label).

:root {
  --bs-focus-ring-width: 0.25rem;
  --bs-focus-ring-opacity: 0.4;
  --bs-focus-ring-color: rgba(184, 148, 31, 0.4); /* gold-700 */
}
[data-bs-theme="dark"] {
  --bs-focus-ring-color: rgba(212, 175, 55, 0.4); /* gold-500 */
}
HTML
<button type="button" class="btn btn-primary">Tab to me</button>
<button type="button" class="btn btn-outline-secondary">Then me</button>
<input type="text" class="form-control w-auto" aria-label="Wrestler name" placeholder="Then the input" />
<button type="button" class="btn btn-link focus-ring focus-ring-navy">Navy ring via .focus-ring-navy</button>

Buttons use :focus-visible, so the ring appears for keyboard users and stays out of the way of mouse clicks. .focus-ring-{color} exists for all eleven theme colors, including .focus-ring-gold, .focus-ring-navy and .focus-ring-cream. See Focus ring.

Reduced motion

Bootstrap already drops per-component transitions under prefers-reduced-motion: reduce ($enable-reduced-motion is on). The theme goes one step further and zeroes the shared transition variables on the root, so anything you build with them stops moving too.

@media (prefers-reduced-motion: reduce) {
  :root {
    --bs-transition-base: none;
    --bs-transition-fade: none;
    --bs-transition-collapse: none;
  }
}

Also covered: the collapse height animation, the toast auto-hide (it waits, then hides instantly), and smooth scrolling (scroll-behavior: smooth is only set under no-preference).

When you write your own transitions, use var(--bs-transition-base) or the .transition-base / .transition-fade utilities and you inherit the behaviour. See Components.

Color contrast

Gold is the brand, and gold is a trap. gold-700 text on the cream page background is about 2.5:1, well short of the 4.5:1 AA target. The theme is set up so the right pairing is the easy one:

  • Gold text: use the emphasis variant. .text-primary-emphasis is a darker gold (#6b5410, about 6:1 on cream). In dark mode it becomes gold-300 on navy (about 10:1).
  • Gold backgrounds: .btn-primary, .btn-gold, .text-bg-primary, .text-bg-warning and .badge.text-bg-gold all get navy-900 text, chosen by Bootstrap's color-contrast() at build time (about 5.9:1 on gold-700, 8:1 on gold-500).
  • Links: navy-700 on cream in light mode, gold-300 on navy in dark. Links stay underlined, so the hover color (gold-700) never carries the meaning alone.
  • Secondary: navy-300 is a mid tone. Neither cream nor navy clears 4.5:1 on it, so Bootstrap falls back to white text for .btn-secondary and .text-bg-secondary.

.text-primary — gold-700 on cream. Decorative only.

.text-primary-emphasis — passes AA. Use this for words.

Champion Challenger Program paper

HTML
<p class="text-primary mb-2">.text-primary — gold-700 on cream. Decorative only.</p>
<p class="text-primary-emphasis mb-2">.text-primary-emphasis — passes AA. Use this for words.</p>
<p class="mb-0"><span class="badge text-bg-gold">Champion</span> <span class="badge text-bg-navy">Challenger</span> <span class="badge text-bg-cream">Program paper</span></p>

Full tables and the contrast rules are on Color.

Every docs page starts with a skip link. It is visually hidden until it receives focus, using Bootstrap's .visually-hidden-focusable. Press Tab once at the top of this page to see it.

Skip to the results

Tab into this example and the link appears.

Results table would start here.
HTML
<a class="visually-hidden-focusable" href="#a11y-skip-target">Skip to the results</a>
<p>Tab into this example and the link appears.</p>
<div id="a11y-skip-target" tabindex="-1" class="p-3 border rounded">Results table would start here.</div>
<body>
  <a class="visually-hidden-focusable" href="#main">Skip to main content</a>
  …
  <main id="main">…</main>
</body>

Give the target tabindex="-1" when it is not a landmark, so focus actually lands there. See Visually hidden.

Autofocus inside popovers

The Popover API moves focus to the first autofocus element when a popover, offcanvas or modal opens, and returns focus to the invoker when it closes. Without autofocus a keyboard user has to Tab across the page to reach the overlay. Add it to the control you expect them to use first.

Search the roster

HTML
<button type="button" class="btn btn-outline-primary" popovertarget="a11y-pop">Find a wrestler</button>
<div class="popover fade" popover id="a11y-pop" data-bs-placement="bottom">
  <div class="popover-arrow"></div>
  <h3 class="popover-header">Search the roster</h3>
  <div class="popover-body">
    <label class="form-label" for="a11y-pop-name">Name</label>
    <input type="search" class="form-control form-control-sm" id="a11y-pop-name" autofocus placeholder="Macho Man" />
  </div>
</div>
Browsers only honour one page-load autofocus. Elements inside a closed popover are not rendered, so they are skipped at load time and focused only when their popover opens. You can use autofocus inside several overlays on one page.

Checklist

  • Headings h1–h3 use the display face. It is a condensed face; keep headings short and never go below 20 px.
  • Every <dialog> and offcanvas has aria-labelledby or aria-label.
  • Toasts carry role="status" (or role="alert" for urgent ones) so they are announced when shown.
  • Tooltip text is CSS-generated and hidden until hover or focus. Do not rely on it for essential information; put that in aria-label or visible text.
  • Do not put a <details> dropdown inside another button. One interactive element per summary.
  • Test with the OS in dark mode and with reduced motion on. Both are automatic in this theme, and both change what users see.