Edit

Support keyboard navigation in a custom visual

  • Article

This article explains how to support navigation through a Power BI visual using the keyboard. Keyboard navigation makes Power BI more accessible to people with disabilities and provides more options for interacting with reports.

The supportsKeyboardFocus feature makes it possible to navigate the data points of the visual by using only the keyboard.

Basic keyboard accessibility features

All visuals come with the following basic keyboard accessibility:

  • Press Esc to move the focus from inside the visual to the visual container.
  • Press Tab from inside a custom visual to navigate through tabbable elements in the visual. Pressing Tab after the last tababble element moves the focus back outside of the visual.

Enhanced keyboard accessibility

To make your custom visual even more accessible, add the supportsKeyboardFocus capability to your visual by adding the following line to the "capabilities.json" file:

    {   
        ...
        "supportsKeyboardFocus": true
        ...
    }

This capability adds the following features to your custom visual:

  • Press Enter when the focus is on the visual container to move the focus to inside the custom visual.
  • Press Tab from inside the custom visual to navigate through tabbable elements. The focus stays inside the visual until you press Esc.

Note

Not all HTML elements are tabbable by default (for example, div and span). Consider adding the correct attribute (e.g tabindex) to these elements to make them tabbable.

Considerations and limitations

  • This feature requires API v2.1.0 or higher.

  • This feature can't be applied to image visuals.

  • Pressing Enter on the visual container won't always land on the first focusable element of the visual. To be sure to start at the first element, focus it programmatically after the focus goes into the visual.

  • After pressing Enter on the visual container and after pressing Tab on the last focusable element, the user might have to press Tab more than once to get to the first element.

Related content