Skip to main content

Develop - keyboard

As detailed on the user experience design keyboard topic, keyboard interaction may be the most critical step to increase the accessibility of a product. Every action a mouse user can do should have a keyboard equivalent. As more designers capture keyboard interaction in wireframes, developers can expect more explicit keyboard guidance. But developers must themselves become more familiar with conventional keyboard interaction. Most wireframing tools capable of outputting functional prototypes emphasize pointer interaction. Developers are usually the first team members who can experience how a design feels to a keyboard user. This is the reason keyboard testing is emphasized in unit testing.

Level 1

Properly code the navigation order

    Ensure interactive elements are reachable with the keyboard

  • What to do

    For users to be able to interact using a keyboard, components must be included in the tab order (so that they take focus when a user navigates a page with the Tab key). Wireframes should indicate to developers both what elements take focus, and in what order. They may also indicate interaction when navigation takes place within a complex widget (usually using arrow keys). Where wireframes do not provide clarity on keyboard navigation, discuss with the design team.

    The code techniques for including elements in the tab order vary depending on the source of the component:

    • Standard HTML. Interactive HTML elements are automatically added to the tab order, based on placement in the Document Object Model (DOM), with no further effort by the developer.

    • Components from a code framework. Check the documentation and perform a keyboard test to ensure each supports tab navigation.

    • Custom elements. Depending on usage, either:

      • Use tabindex=”0” to add a focusable element naturally into the tab order, according to its placement in the DOM.
      • Use tabindex=”-1” to remove the element from the initial tab order. Then make it focusable using element.focus() for dynamic elements such as dialog.
    <!-- Set tab order according to DOM -->
    <div tabindex="0">Div with tabindex set to 0, 1st tab stop</div>
    <div>Div with no tabindex, *NO* tab stop</div>
    <button type="button">Button, 2nd tab stop</button>
    <a href="pretend_target.html">Link, 3rd tab stop</a>
    <div tabindex="0">Div with tabindex set to 0, 4th tab stop</div>
    Requirements and resources
    Related toolkit topics
  • Where possible, achieve the desired tab order by adjusting the DOM, rather than overriding the tabindex

  • What to do

    Correctly ordering content in the Document Object Model (DOM) is the preferred way to achieve a focus order. The order can also be adjusted programmatically, but there are accessibility considerations with most of the techniques.

    When dynamic content is inserted, you must take care to insert the content in the correct place in the DOM to maintain a logical tab order.

    Ensure that when a dialog appears because of a user action, focus is set on an interactive element within it. When the dialog is dismissed, return the focus to a logical place, typically the element that caused the dialog to appear. Consult with the UX designer to ensure smooth transitions of focus.

    Use caution setting the tabindex attribute on elements to a number greater than zero, which causes them to receive focus before focusable elements that lack tabindex or have tabindex="0". After all the elements with a tabindex greater than zero have received focus, the rest of the elements receive focus in the order they appear in the DOM.

    <!-- Set tab order according to DOM -->
    <div tabindex="0">This is 1st tab stop</div>
    <div tabindex="0">This is 2nd tab stop</div>
    <div tabindex="-1" role="dialog" aria-modal="true"
    aria-label="This won’t be in tab order after second div until set by script">
    <div tabindex="0">This is 3rd tab stop</div>
    Requirements and resources
    Related toolkit topics
  • When overriding the default focus indicator, confirm focus is highly visible

  • What to do

    When an object takes keyboard focus, it must visually display a focus indicator. By default, interactive HTML elements will receive a focus indicator from the browser. Any time the design calls for an override of the default focus indicator, implement a replacement focus indicator that is highly visible, as per the design.

    Good example: visible blue border surrounding first option in list

    Ensure focus is highly visible, if it's not the default indicator, so that users know where the keyboard focus is.

    Bad example: light grey shaded area filling first option in list

    Don't use insufficient contrast, such as this slight variance in background color, which makes it difficult for users to know where the keyboard focus it.

    The following practices remove the focus indicator and need remediation or a replacement focus indicator controlled by scripting:

    • CSS style outline:0
    • CSS style outline:none
    • onfocus="blur" This should be avoided because the keyboard user cannot interact with the element.

    The following resolves a missing focus indicator by using the CSS property outline (here adding a really obvious thick, dotted red line!), and also adds some space between the elements and indicator with use of the CSS property outline-offset.

    /* The following resolves missing focus indicator by use of CSS properties outline and outline-offset */
    *:focus {
    outline: 2px dashed red;
    outline-offset: 2px;
    Requirements and resources
    Related toolkit topics

Implement established keyboard conventions

    Use standard HTML elements where possible, using CSS to alter appearance not behavior

  • What to do

    Standard HTML elements are built with full keyboard operability. The keys used to operate HTML elements are predictable, and consistent with keys used to operate native operating system elements of the same type. Use of HTML elements reduces the work for a developer because the browser handles the keyboard functionality for the element.

    If the design shows a certain visual treatment for an HTML element, override the default browser styling and use CSS to change its appearance.

    <!DOCTYPE html>
    input[type=text] {
    width: 100%;
    padding: 12px 18px;
    margin: 8px 0;
    box-sizing: border-box;
    Requirements and resources
    Related toolkit topics
  • Be familiar with established keyboard conventions

  • What to do

    Standard HTML elements already have well thought out keyboard functionality built in. The keyboard operation closely models what works for similar components in desktop operating systems, making navigation and usage predictable for the user.

    However, there are many operating system components that don’t exist natively in HTML, such as menus and sliders. Accessible Rich Internet Application (ARIA) markup was created so developers can build custom components that consistently work with assistive technologies. Implement keyboard handlers using established conventions to give full keyboard access to the functionality of the component. For predictable usage via a keyboard, it is best to implement keyboard access consistent with the patterns found in the ARIA authoring practices.

    Be cautious when using a code framework or design system with custom-built components and patterns. Many frameworks were not built or maintained with accessibility in mind. Check the documentation and verify keyboard operability of all functionality. Any time the keyboard operation of a custom component departs from convention, discuss the reasons and risks with design.

    Requirements and resources
    Related toolkit topics
  • Implement keyboard operation for custom elements

  • What to do

    Once the keyboard operation is fully defined, use ARIA techniques to implement any custom components. When using a UI component library, use only components that have a full implementation of keyboard access. For all other components, use the ARIA authoring practices and examples to guide keyboard implementation. Remember that although you can assign roles through ARIA, you still need to implement all keyboard interaction using events like onkeydown.

    Wireframes may specify where navigation has been improved by grouping controls to reduce tabbing. This is most common in composite components, such as navigation trees and toolbars where the tabindex attribute and aria-activedecendent property can be used to manage navigation within a component. The ARIA authoring practices provide keyboard operation guidance, as well as working examples where you can examine coding techniques.

    Requirements and resources
    Related toolkit topics

Level 2

Ensure keyboard access to complex interactions

Level 3

Code screen updates predictably