mintlify__docs/guides/accessibility/keyboard.mdx

---
title: "Keyboard navigation"
description: "Ensure your documentation is fully navigable without a mouse by testing keyboard access and understanding focus management."
keywords: ["keyboard navigation", "focus", "tab order", "keyboard shortcuts"]
---

Many users navigate documentation using only a keyboard. This includes people with motor disabilities, power users who prefer keyboard shortcuts, and anyone who can't use a mouse. Your documentation should be fully accessible via keyboard.

## Why keyboard navigation matters

Keyboard navigation is essential for:
- Users with motor disabilities who cannot use a mouse
- Screen reader users who rely on keyboard commands
- Power users who prefer keyboard efficiency
- Users with broken or missing pointing devices
- Anyone navigating on devices without touch or mouse input

When you ensure keyboard accessibility, you also improve the experience for screen reader users, since screen readers rely on keyboard navigation.

## Test keyboard navigation

Navigate through your documentation using only your keyboard to identify issues:

1. Press <kbd>Tab</kbd> to move forward through interactive elements
2. Press <kbd>Shift</kbd> + <kbd>Tab</kbd> to move backward
3. Press <kbd>Enter</kbd> to activate links and buttons
4. Press <kbd>Space</kbd> to activate buttons and toggle controls
5. Use arrow keys to navigate within components like dropdowns and tabs

### What to check

**All interactive elements are reachable**

Every link, button, form field, and interactive component should be accessible via keyboard. If you can't reach an element with <kbd>Tab</kbd>, it's not keyboard accessible.

**Focus order is logical**

The tab order should follow the visual layout of the page. Users should move through content in a predictable sequence that matches how they read the page.

**Focus indicators are visible**

When you tab to an element, you should see a clear visual indicator showing which element has focus. This is typically an outline or highlight around the element.

**No keyboard traps**

Users should be able to navigate into and out of all components. A keyboard trap occurs when focus gets stuck in a component with no way to escape using the keyboard.

## Understand focus indicators

Focus indicators show which element currently has keyboard focus. Mintlify provides default focus indicators, but if you customize your theme, ensure focus indicators remain visible.

### Default focus behavior

Browsers provide default focus indicators (usually a blue or black outline). These meet basic accessibility requirements, but you can enhance them for better visibility:

```css
/* Example of enhanced focus indicator */
a:focus,
button:focus {
  outline: 2px solid #0066cc;
  outline-offset: 2px;
}
```

### Never remove focus indicators

Removing focus indicators makes your documentation unusable for keyboard users:

```css
/* Never do this */
*:focus {
  outline: none;
}
```

If you don't like the default focus indicator appearance, replace it with a custom style that's equally or more visible.

## Interactive components

Mintlify components are built with keyboard accessibility in mind. Understanding how they work helps you use them effectively.

### Tabs

Users can navigate between tabs using arrow keys:

```mdx
<Tabs>
  <Tab title="JavaScript">
    JavaScript code example
  </Tab>
  <Tab title="Python">
    Python code example
  </Tab>
</Tabs>
```

Keyboard interaction:
- <kbd>Tab</kbd> moves focus to the tab list
- <kbd>Arrow Left</kbd> / <kbd>Arrow Right</kbd> navigate between tabs
- <kbd>Enter</kbd> or <kbd>Space</kbd> activates the focused tab

### Accordions

Accordions expand and collapse with keyboard input:

```mdx
<Accordion title="Show details">
  Additional content here
</Accordion>
```

Keyboard interaction:
- <kbd>Tab</kbd> moves focus to the accordion header
- <kbd>Enter</kbd> or <kbd>Space</kbd> toggles expansion
- Content inside expanded accordions is included in tab order

### Code blocks

Code blocks should be accessible but not trap keyboard focus:

````mdx
```javascript
function example() {
  return "accessible code";
}
```
````

Users can:
- <kbd>Tab</kbd> to the code block
- <kbd>Tab</kbd> again to move past it
- Use the copy button with <kbd>Enter</kbd>

## Skip links

Skip links allow keyboard users to bypass repetitive navigation and jump directly to main content. Mintlify includes skip links by default.

When a user presses <kbd>Tab</kbd> on a page, the first focusable element is typically a "Skip to content" link. Activating this link moves focus to the main content area.

## Forms and inputs

If your documentation includes forms or custom input fields, ensure they're keyboard accessible:

### Label all inputs

Every input needs an associated label:

```html
<!-- Good -->
<label for="email">Email address</label>
<input type="email" id="email" name="email" />

<!-- Not accessible -->
<input type="email" placeholder="Email address" />
```

### Provide keyboard access to custom controls

If you create custom form controls, ensure they work with keyboard:

```html
<!-- Custom checkbox example -->
<div role="checkbox" 
     aria-checked="false" 
     tabindex="0"
     onKeyPress={(e) => {
       if (e.key === 'Enter' || e.key === ' ') {
         toggleCheckbox();
       }
     }}>
  Custom checkbox
</div>
```

## Keyboard shortcuts

If you implement custom keyboard shortcuts, follow these guidelines:

### Avoid conflicts with browser and screen reader shortcuts

Don't override standard shortcuts like:
- <kbd>Ctrl</kbd> + <kbd>F</kbd> (find)
- <kbd>Ctrl</kbd> + <kbd>T</kbd> (new tab)
- <kbd>Ctrl</kbd> + <kbd>W</kbd> (close tab)
- Screen reader shortcuts (varies by screen reader)

### Provide a way to discover shortcuts

Document available keyboard shortcuts in your documentation:

```mdx
## Keyboard shortcuts

- <kbd>Ctrl</kbd> + <kbd>K</kbd> - Open search
- <kbd>/</kbd> - Focus search input
- <kbd>Esc</kbd> - Close modals and overlays
```

### Make shortcuts optional

Users should be able to accomplish tasks without keyboard shortcuts. Shortcuts should enhance efficiency, not be the only way to perform actions.

## Common keyboard navigation issues

### Issue: Links that look like buttons

If you style a link to look like a button, it should still behave like a link:

```mdx
<!-- Good - link behavior -->
[Get started](/quickstart)

<!-- Good - button behavior -->
<button onClick={handleClick}>Submit</button>

<!-- Confusing - looks like button, acts like link -->
<a href="/quickstart" class="button-style">Get started</a>
```

### Issue: Click-only interactions

Avoid interactions that only work with mouse clicks:

```javascript
// Bad - only works with mouse
<div onClick={handleClick}>Click me</div>

// Good - works with keyboard
<button onClick={handleClick}>Click me</button>
```

### Issue: Hover-only content

Content that only appears on hover is not accessible to keyboard users:

```mdx
<!-- Bad - tooltip only on hover -->
<span title="Additional info">Hover me</span>

<!-- Good - accessible tooltip -->
<Tooltip content="Additional info">
  Interactive element
</Tooltip>
```

## Testing tools

### Manual testing

The most effective way to test keyboard navigation is to use your documentation with only a keyboard. Disconnect your mouse or don't touch your trackpad while navigating.

### Browser developer tools

Most browsers include accessibility inspection tools:

**Chrome DevTools**
1. Open DevTools (<kbd>F12</kbd>)
2. Go to Elements tab
3. Select Accessibility pane
4. Inspect focus order and ARIA attributes

**Firefox Accessibility Inspector**
1. Open Developer Tools (<kbd>F12</kbd>)
2. Go to Accessibility tab
3. Check keyboard navigation and focus order

### Automated testing

Use browser extensions to identify keyboard accessibility issues:

- [axe DevTools](https://www.deque.com/axe/browser-extensions/) - Comprehensive accessibility testing
- [WAVE](https://wave.webaim.org/extension/) - Visual accessibility evaluation
- [Lighthouse](https://developers.google.com/web/tools/lighthouse) - Built into Chrome DevTools

## Best practices summary

1. **Test with keyboard only** - Navigate your entire documentation using only keyboard
2. **Maintain visible focus indicators** - Never remove focus outlines without replacing them
3. **Follow logical tab order** - Ensure focus moves in a predictable sequence
4. **Avoid keyboard traps** - Users should always be able to navigate away from components
5. **Label interactive elements** - All buttons, links, and inputs need clear labels
6. **Support standard shortcuts** - Don't override browser or screen reader shortcuts
7. **Provide alternatives to hover** - Ensure hover-only content is accessible via keyboard

## Related topics

- [Content structure and semantics](/guides/accessibility/structure) - Use proper heading hierarchy and semantic HTML
- [Testing and validation](/guides/accessibility/testing) - Use tools to identify and fix accessibility issues
- [Color and visual design](/guides/accessibility/color) - Meet contrast requirements for focus indicators