Overview

PayPal provides an excellent library that extends a few of Bootstrap's default complex components to enhance use with Assistive Technologies. Using a correct structure alleviates the need to provide custom event handling and keyboard navigation. The caveat is the structure must be closely followed. The PayPal assistive library enhances the following components:

• Modal
• Tabs
• Dropdown
• Alerts
• Accordion
• Carousel

Nearly every custom component we use can be abstracted into one of these objects, and as such it would be prudent to abstract these components into views/templates that are easily implemented without the need of a developer to concern him or herself with maintaining the proper structure and roles. That said, PayPal recommends avoiding the carousel object, as it does not adequately meet WCAG 2.0 standards.

This page is meant to serve as an example of implementations and possible uses for each enhanced component, as well as what custom work is needed when all of the events are not handled by default. Enhanced components do not necessarily follow standard Bootstrap patterns, so it would be wise to not follow Bootstrap class patterns when attempting to ensure accessibility.

Not all Assistive Technologies work the same and some default keyboard navigation functionality may be overridden. Also note that some glitches may occur with non linear navigation, such as dropdowns, where Bootstrap handles focus. In these cases the screen reader may attempt to read the following tab-able element before reading the dropdown. This generally can't be avoided, and is a race condition. Another glitch that may occur is that certain items may be read twice.

A few patterns that need to be observed which are currently often not followed:

• All group-able objects need proper roles assigned. Bootstrap's API can be referenced for this, but things such as grouped buttons, lists, and navigation elements have specific aria roles which need to be applied to the parent container and each element within. The source HTML on this page can be used as a starting reference.

• Any route control must have an element with the same id within the page. For instance, ehmp-ui/#overview needs and element with id="overview" in order for Assistive Technologies to be notified of content changes. Any anchor with href="#some_id" needs a corresponding element with the appropriate id.

• The ALT attribute should never be used. To notify the screen reader of any alternate data attributes, use a span or div with class="sr-only", or add a title attribute directly to an actionable element.

• Using custom focus modifiers or custom key event handling is generally not only unwarranted, but will cause undesired behavior. Before designing a template, start with determining which one of these enhanced components best fits the needs of the design. For instance, any floating dialogs should be abstracted to a modal. Dynamic content attached directly to a DOM element should use a dropdown. In the case where an example uses a button or anchor in some, but not all cases, other elements that are by default non-functional can be substituted so long as tabindex="0" and role="button" are added (and are imperative in order to meet compliance). See the media dropdown below. Note that element substitution may require custom event handling and as such is not recommended. Manually setting focus can lead to keyboard navigation traps.

JUMP TO...

• Modaljump to modal
• Tabsjump to tabs
• Dropdownjump to dropdown
• Alertsjump to alerts
• Accordionjump to accordion
• Other Componentsjump to other components
• Custom Componentsjump to custom components
• External Linksjump to external links

• MODAL

  • User activates modal button and modal dialog is announced and modal dialog takes focus, which causes Assistive Technologies to read contents.
  • The tab key will navigate through the modal's actionable items and will not allow the user to tab outside of the modal until it has been closed.
  • Activating button which has data-dismiss="modal" or hitting escape key by default will close modal and return focus to trigger button (so long as trigger button has data-toggle and data-target attributes) without the need for custom coding. If the trigger button uses JavaScript to toggle the modal, the developer will need to custom code focus handling to return focus to trigger button.

  ×

  Modal Heading

  Here is all my content

  Close Save changes

  OPEN MODAL
  
  

• TABS

  • When user navigates to tab group, the first tab into the group will land on the tab that has class="active" applied.
  • Navigation between tabs is accomplished with arrow keys. Arrow navigation will cause selection wrap (on the last item, a right key will land on the first item).
  • Tabbing from the tab group will land on the contents of the tab-content area and Assistive Technologies will read the contents. From here, shift+tab will navigate back to the active tab, and tab will move out to the next actionable item in the DOM.

  STANDARD TAB

  • TAB1
  • TAB2
  • TAB3

  Contents of Tab #1

  Contents of Tab #2

  Contents of Tab #3

  
  

  REVERSED TAB

  This is meant to demonstrate that the placemenet is not important. However, it should be noted that this format is discouraged since the DOM order is illogical for keyboard navigation. In general, actionable elements should be in the DOM before dynamic content.

  Search for something

  DO SOMETHING

  Display something

  • TAB 1
  • TAB 2
  • TAB 3

  
  
  

• DROPDOWNS

  • When user navigates to dropdown, space, enter, click, or down arrow will open the dropdown. The first element will take focus automatically. Some Assistive Technologies will override the behavior and may assert that a tab is required to focus on the first element.
  • Navigation between dropdown items is accomplished with arrow keys. Arrow navigation does not wrap. If there is only one list item, as is the case for the media dropdown example, arrow keys do nothing.
  • Tabbing from the dropdown will land on the next actionable item and the dropdown will be closed. Shift tab will land on the dropdown activation button and automatically close the dropdown and announce that it is collapsed.

  DROPDOWN FOR NAV

  Dropdown

  • Action
  • Another action
  • And another action

  
  

  MEDIA DROPDOWN

  THIS IS PART OF THE BUTTON THAT OPENS MY DROPDOWN (style is irrelevant on this element)

  • • Some stuff to display
    • Some more stuff to display

  
  
  

• ALERTS

  • An alert is a simple component that requires some custom handling of focus events. See this source code for examples on how to handle this. In this example, when the alert is dismissed, the page will need to be reloaded to trigger it again. Data-dismiss on an alert destroys the DOM element, but custom code may be required to destroy the Backbone view.
  • Dismissable alerts should be used for server side error handling and fixed alerts should be used for client side validation.
  • A Dismissable alert takes focus when it is made visible, and when dismissed focus returns to the actionable element that triggered the alert
  • Fixed alerts take focus when a validation error occurs. The actual alert should be an actionable element which returns focus to the element that failed validation.

  DISMISSABLE ALERT

  This action triggers an alert

  FIXED ALERT

  enter some text and press enter (requires more than 3 characters)

  
  
  

• ACCORDION

  • When user navigates to an accordion, the accordion header that corresponds with the accordion body containing class="in" will be selected.
  • Tab from an accordion header will enter the accordion body and announce the contents. Another tab will leave the accordion object all together. Shft+tab from the accordion body will select the tab corresponding to the accordion body.
  • Navigation between accordion headers is accomplished using the up and down arrow keys and this selection wraps.

  ACCORDION

  Collapsible Group Item #1

  We apply the class 'in' to the div, which contains the collapse field to default to an accordion item being rendered by default.

  Collapsible Group Item #2

  The class 'in' is automatically applied to my ancestor which contains the 'collapse' class when we toggle the accorion item.

  Collapsible Group Item #3

  Note that these are aggregated as a group and with this implementation only one accordion item will be visible at a time. Functionally this item is handled as a sort of horizontal tab structure.
  
  
  

• OTHER COMPONENTS

  These components are not keyboard navigable. Instead, the title attribute and spans using class="sr-only" are used to inform Assistive Technologies. The span approach is redundant since title or data-original-title must be supplied but not all Assistive Technologies work the same.

  • TOOLTIPS

    Here is an example of a tooltipUsing an anchor tag...
    ...and here one with a button Tooltip ButtonTooltip on left
    ...and using a span |hover meI'm a span tooltip|
    

    • Note that one should not use ALT attributes under any circumstance to aid the Assistive Technologies. Instead use a span with class="sr-only", or simply a title attribute.
    • $('[data-toggle="tooltip"]').tooltip(); must be explicitly called to initialize tooltips. It is opt-in only.

  • POPOVER

    Dismissible popoverThis is the content that will be displayed in the popover

    • Like tooltip, use a span with class="sr-only" to inform Assistive Technologies of data-content
    • Always use an anchor to ensure cross-browser compatibility. Tabindex is required as well.
    • $('[data-toggle="popover"]').popover(); must be explicitly called to initialize popover. It is opt-in only.

  
  
  

• CUSTOM COMPONENTS

  There will be times when no Bootstrap object satisfies the needs of the design. In these cases, it will be entirely up to the developer to implement an adequate solution. The following is one of these cases. There is a grid that when an item within the grid is clicked information in a box to the right will be updated dynamically. To satisfy 508, when this click happen, focus needs to shift to the box that was updated. Shift+tab needs to return focus to the row that triggered the change. Arrow key navigation will be used in the grid itself.

  Collapsible Group Item #1

  Collapsible Group Item #2

  Collapsible Group Item #3

  Everyone is pointing to me! I'm going to swap out some content dyanmically when you click the links

  
  
  

• EXTERNAL REFERENCES

  • WCAG 2.0 Documentation
  • PayPal Accessibility Library (Click link in header to load library)
  • Bootstrap Components
  • VA Section 508