How do I make my unique custom widget accessible?


I’ve built a unique custom widget that doesn’t match any of the existing ARIA design patterns. How should I code it to be accessible?


In strong user design, the goal is that as many users as possible can efficiently understand and interact with what you’ve built. Accessible Rich Internet Applications, or ARIA, can be a powerful tool for improving accessibility when used correctly, but may not have an exact pre-existing pattern to describe your widget. Consider your options:

Divide and simplify

Can the functions of your widget be broken down into separate components or steps? Including a separate element for each function makes it easier to communicate accurate roles, names, and other information to users of assistive technology.

One example is a navigation bar link that can be clicked to go to a new page or hovered to expose more links. This one element functions as both a link (that loads a new page) and a button (that exposes more content). Both functions need to be communicated clearly to all users, and no single ARIA role conveys this information. One strategy is to divide the two functions into two elements: a link element that controls the navigation, and a button element that controls exposing the links.

Choose the closest ARIA pattern

Based on the widget’s function, is there an existing pattern that is close and could be supplemented with additional instructions? If you choose this option, the instructions should be both visible and programmatically related to the widget.

Keep in mind that function, not design, is typically the more important consideration when choosing an ARIA design pattern. A widget may have a unique look, but a familiar function.

For example, if the widget’s core function is for users to select a single option out of a group of options, a radio group or listbox pattern may be appropriate, even if it doesn’t look like a traditional version. If the user’s selection changes the content in a section of the page, then the tab pattern may be the best fit.

Use the application role

Is your widget truly too complex and different to use an existing pattern? The application role may be appropriate. However, this strategy must be used with care. The application role is open ended, but also requires you as the author to handle all accessibility characteristics such as keyboard navigation, focus management, text, instructions, and more.

Remember: focus on the end goal to communicate clearly. Ideally users spend their time and energy absorbing your content and completing the task at hand, not puzzling through your widget.

For a deeper dive into common ARIA design patterns, explore the Widgets course from Accessible Web Academy, sign up for our web accessibility tools or our WCAG testing software.

Free Tools to Continue Learning

Accessible Web Company Logo

Accessible Web RAMP

Monitor your website and manage your progress towards WCAG conformance.

Accessible Web Company Logo

Accessible Web Academy

Career specific courses to help power up your accessibility knowledge.