# Focus and keyboard
Focus rings, skip links, tabindex, focus trapping and the APG keyboard patterns.
## Focus rings
Style `:focus-visible`, not bare `:focus`. The browser shows it for keyboard and assistive-tech focus and suppresses it for mouse clicks, where focus is already obvious. Never write `outline: none` or `focus:outline-none` without a visible replacement, which removes keyboard navigation for sighted keyboard users.
Prefer the browser's unmodified focus indicator, which adapts to platform and forced-color settings without the author predicting every background. Adding only `outline-offset` preserves it. A custom `outline: 2px solid` with no color renders `currentColor`, which is not automatically accessible, because the outline may cross colors unlike the text's own background. The preference order:
```css
/* Best: keep the browser ring, just give it breathing room */
:focus-visible {
outline-offset: 2px;
}
/* Custom ring when the design requires one: use the project's verified token */
:focus-visible {
outline: 2px solid var(--focus-ring);
outline-offset: 2px;
}
```
```tsx
// Tailwind: use the project's focus token or established focus-ring utility
```
A custom focus indicator must meet the applicable project or WCAG target for visible area and change of contrast. Inspect the whole perimeter against every adjacent color it crosses: component fills, page surfaces, images, gradients, hover and selected states. A token, brand color, or `currentColor` passes only when that rendered check does.
In `forced-colors: active` (Windows High Contrast), keep the default color adjustment or name a system color such as `Highlight`. `forced-color-adjust: none` freezes the authored color, so use it only where you have checked the control stays perceivable.
Group focus styles with `:focus-within` when a wrapper should light up while an inner input has focus (e.g. a search box with an icon inside the border).
## Skip link
Target `` and visually hide the link until focused:
```css
.skip-link {
position: absolute;
inset-inline-start: -999px;
}
.skip-link:focus {
inset-inline-start: 16px;
top: 16px;
}
```
```html
Skip to content……
```
Give in-page anchor targets `scroll-margin-top`, such as `80px` under a sticky header, so the target isn't hidden when jumped to.
## tabindex rules
- `tabindex="0"`: adds an element to the natural tab order. Only for custom interactive elements that aren't natively focusable.
- `tabindex="-1"`: focusable via JavaScript only (`el.focus()`). Use for headings you move focus to, modal containers and roving-tabindex members.
- Positive `tabindex`: never. It hijacks the tab order for the whole page. Fix the DOM order instead.
### Roving tabindex
Composite widgets, meaning tabs, menus, toolbars and radio groups, occupy one Tab stop. The active item has `tabindex="0"`, all others `tabindex="-1"`, and arrow keys move both focus and the `0`:
```tsx
{tabs.map((tab, i) => (
))}
```
## Focus trapping and restoration
Modals must trap focus. Put `inert` on everything behind the dialog, which removes background content from the tab order and from assistive tech in one move:
```tsx
// On open
document.getElementById("app-content").inert = true;
const dialog = dialogRef.current;
(dialog.querySelector("[autofocus]") ??
dialog.querySelector("button, [href], input, select, textarea"))?.focus();
// On close
document.getElementById("app-content").inert = false;
triggerRef.current?.focus(); // always return focus to the element that opened it
```
Prefer native `