# Custom Widgets and Controls ## expand\_more Extending web site and application functionality through custom widgets and controls can significantly improve the user experience for everyone, making complex tasks possible via a web interface without requiring specialist software. For interactive elements to be accessible, they must be keyboard operable and they must expose essential descriptive information, including the element’s name, role, and current state or value, in an accessible way so that assistive technologies can report this information. Native interactive HTML elements such as an input and button have always provided a high degree of accessibility by default. If more complex user interface widgets and controls are used, accessibility must be added with additional markup and scripting. Thankfully, the [W3C Accessible Rich Internet Applications (WAI-ARIA) specification](http://www.w3.org/TR/wai-aria/) provides a standard way to add additional accessibility information to code. The work required to ensure accessibility of custom controls can take extra time, and the more complex the control, the more complex the work will be. When third party user interface libraries and frameworks are used, it’s essential to check to what extent this additional accessibility information is reliably provided, and where additional work will be needed to add it. See also [Keyboard](/keyboard "Keyboard") and [Notification](/notifications-and-alerts "Notifications and Alerts") ## Use Accessible Design Patterns When using custom widgets and controls to construct a web page or application, the first requirement is that they are appropriate for the task they are intended to support, such as: data entry, controlling what content is displayed on screen, or navigation. - **Make sure widgets and controls are appropriate for the task at hand.** Accessibility problems can emerge when users find it difficult to understand what it is that they’re supposed to do and how they should operate it. - **Make sure widgets and controls follow recognized design patterns for accessibility**. In almost all cases, this will require the use of WAI-ARIA markup plus JavaScript to manage keyboard interaction, and CSS to provide suitable visual styling to content. Design patterns should mirror the behavior of the component’s equivalent desktop version. - **Check accessibility support within third-party UI libraries**. If you’re using a third party UI library, read the documentation to understand as much as possible about its out-of-the-box accessibility support and the areas where you’ll have to add accessibility support that’s missing. ### Testing For each custom widget and its controls, check: - Is the widget appropriate for the task it is intended to support? - Does the behavior of the widget and its controls match its relevant design pattern? ## Provide Name, Role, and Value Information Users of assistive technologies must understand what a custom control is and what it does. Custom controls that lack accessibility information become difficult or impossible to understand or operate. Using WAI-ARIA provides a way to fill in missing accessibility information so that assistive technologies can recognize custom controls as controls and not as div or span elements without semantic meaning or value. - **Provide an accessible name for each custom component.** An accessible name is effectively the label for a control, explaining what it does. For custom components, the corresponding design pattern defines the best way to provide the accessible name. - **Provide controls for which the visible text label matches the accessible name**. \[*Note*: *The programmatic label of a control is its accessible name.*\] When the accessible name is different from the visible label, it essentially becomes an unknown hidden command for speech input users that can be accidentally activated without the user knowing what has happened. - **Provide an accessible role for each custom component.** WAI-ARIA defines a large number of values for the role attribute, which are used by assistive technologies to convey the component’s purpose. Give each custom control a suitable role attribute, such as role="button" for custom buttons or role="slider" for slider widgets. - **Provide and maintain an accurate states and values for each custom component.** This means giving custom form components, such as sliders, suitable values that represent their current value plus any additional required values, such as maximum and minimum possible. For controls that change visual appearance, such as a menu item with an associated dropdown menu or a button that is a show/hide toggle button for additional content, their current state must reflect whether their associated content is shown. ### Testing Use a code inspector (see the [Accessibility Testing Tools and Practices](/testing "Accessibility Testing Tools and Practices") page for examples) to query each interactive control for its name, role, and current state or value information. - Is this information provided? - If so, is it accurate? - Does the visible name match the accessible name? - When you interact with the control, is its current state and value updated? Validate your answers by using a screen reader to interact with the widget. Is this accessibility information exposed meaningfully and understandably? ## Design Controls for Easy Operation With custom controls, developers have an additional responsibility to ensure that the control can be operated effectively by people with disabilities, beyond ensuring keyboard operation and visible focus indication. This is particularly important for supporting effective touchscreen interaction, for example via a smartphone. - **Make sure that the control is big enough to operate.** The size should be large enough that people with reduced dexterity or vision can activate it without undue effort, with using a mouse, through touch or other input method. 24x24px is the minimum but 44x44px is recommended, especially for touchscreen use, so that they are large enough for users to activate. - **Make sure that controls are sufficiently spaced apart.** For all controls, including custom controls, follow best practice in usable interface design to ensure that adjacent controls are spaced apart sufficiently to minimize the chance of the wrong control being inadvertently activated. - **Make sure that controls are positioned to minimize impact of error.** Be careful when placing pairs of controls where inadvertently selecting one instead of the other could have significant consequences (such as adjacent Save and Delete buttons). - **Make sure that controls have sufficient color contrast.** Active user interface components (e.g., buttons) and meaningful graphics must be distinguishable by people with moderately low vision. The visual presentation of user interface components and graphical objects needs to have a contrast ratio of at least 3:1 against adjacent colors. - **Make sure that content can be operated using simple inputs on a wide range of pointing devices**. Any functionality that operates by using multipoint or path-based gestures, can be operated with a single pointer (e.g., finger, stylus, eye-gaze, head pointer), unless a multipoint or path-based gesture is essential. Single pointer functionality is especially important for people with mobility impairments. - **Design interfaces to minimize accidental or erroneous input by users**. It is critical for people with motor impairments and/or cognitive disabilities to be able to cancel a pointer function in order to prevent unintended results. Developers need to ensure that completion of the action occurs when a user releases a pressed mouse button, lifts a finger or pointer, or releases a key (i.e., up event, not the down event) and the user can abort the action or undo it after completion. The down event can be used, if essential (e.g., piano-playing simulation). - **Make sure that functions that are triggered by moving a device can also be operated by conventional user interface components**. For people with limited mobility, for those whose device must remain in a fixed position, and for others with a variety of needs, it's critical that another method beyond device motion (e.g., tilting, shaking) exists to complete a task. ### Testing For each custom actionable control: - View the control on an Android or iOS smartphone. Measure the size of the control. Is it at least 9.6mm across? - Is there sufficient spacing between the control and any neighboring active controls? - Do neighboring controls have sufficient error handling capability so that inadvertently selecting one does not have irreversible consequences? - Does the control (e.g., button) have at least a 3:1 contrast against adjacent colors? \[*Hint*: Test with a [contrast testing tool](https://accessibility.huit.harvard.edu/color#contrast-testing-tools).\] - Can the control be activated with a single input? - Can the control be activated on the pointer or key up event? - Can functions that are triggered by moving a device also be operated by conventional user interface components? ## More Information - [ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/), specifically the [Patterns](https://www.w3.org/WAI/ARIA/apg/patterns/) - [Practical ARIA Examples (Heydon Pickering, Internet Archive copy)](https://web.archive.org/web/20190924084113/http://heydonworks.com/practical_aria_examples/) - [Understanding SC 2.5.3—Label in Name (WAI)](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html) - [Understanding SC 4.1.2—Name, Role, Value (WAI)](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) - [Léonie Watson: Understanding Screen Reader Interaction Modes](http://tink.uk/understanding-screen-reader-interaction-modes/) (useful background information on how screen readers render web content) - [Accessible Name Calculation](https://www.w3.org/TR/html-aapi/#accessible-name-and-description-calculation) (HTML to Platform Accessibility APIs Implementation Guide)—detailed description of accessible name-calculation for elements - [Understanding WCAG SC 1.4.11—Non-text Contrast (WAI)](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) - [Understanding WCAG SC 2.5.1—Pointer Gestures (WAI)](https://www.w3.org/WAI/WCAG22/Understanding/pointer-gestures.html) - [Understanding WCAG SC 2.5.2—Pointer Cancellation (WAI)](https://www.w3.org/WAI/WCAG22/Understanding/pointer-cancellation.html) - [Understanding WCAG SC 2.5.4—Motion Actuation (WAI)](https://www.w3.org/WAI/WCAG22/Understanding/motion-actuation.html) - [Understanding WCAG SC 2.5.8—Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) - [Understanding WCAG SC 2.5.5—Target Size (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) ## Related Techniques [### ✎ Technique: Non-text contrast ](/technique-non-text-contrast)The contrast of icons and graphical objects is just as important as that of text. Use sufficient contrast for all elements on the screen, with a minimum contrast ratio of 3:1. [### ✎ Technique: Pointer gestures ](/technique-pointer-gestures)All operations must use simple gestures that need only a single touch. If the site or application does use multi-touch gestures, be sure to also provide simple interfaces. [### ✎ Technique: Label in name ](/technique-label-name)People with disabilities rely on interface controls that are used programmatically. These controls have a visual label, as well as a programmatic label, known as its Accessible Name. [### ✎ Technique: Motion actuation ](/technique-motion-actuation)Ensure that functions that are triggered by moving a device or by gesturing towards the device can also be operated by more conventional user interface components. [### ✎ Technique: Differentiating controls ](/technique-providing-controls)Placement of controls affects their ease of use. [### ✎ Technique: Autocomplete input controls ](/technique-aria-autocomplete)Autocomplete widgets can be helpful for accessibility because they can make it easier to enter text by providing suggestions based on the characters initially typed. [### ✎ Technique: Required fields ](/technique-required-fields)A clear indication that specific form fields are required can save users time and avoid potential errors relating to missing data when a form is submitted. [### ✎ Technique: Accessible modal dialogs ](/technique-accessible-modal-dialogs)Modal dialogs can enhance usability by focusing attention on a specific message that requires a user action to continue. An accessible modal dialog is one where keyboard focus is managed properly, and the correct information is exposed to screen readers. [### ✎ Technique: Expandable sections ](/technique-expandable-sections)Expandables (sometimes called “collapsible” or “disclosure widgets”) are simple interface patterns that allow you to expand and collapse content. [### ✎ Technique: Accessible names for buttons ](/technique-accessible-names-for-buttons)Whether you provide controls using standard HTML elements or create custom controls, ensure that controls are given appropriate names. [### ✎ Technique: Hit areas ](/technique-hit-areas)Interactive elements should not be difficult to select or activate when using a mouse or a touchscreen. Generous sizing and spacing is important, and their implied visual “hit area” should correspond to the control’s active area. [### ✎ Technique: Managing focus and inactive elements ](/technique-managing-focus-and-inactive-elements)If an active element is intended to be unavailable in a particular state and it’s hidden from view, it should not be able to receive focus. [### ✎ Technique: Keyboard accessible links ](/technique-keyboard-accessible-links)Links (`` elements) are focusable by default, so it should normally be possible to activate them using the keyboard. However, under certain circumstances, they are not focusable. [### ✎ Technique: Input labels ](/technique-input-labels)Descriptive labels help users understand the purpose of a form control. Labels should be associated with their controls so that when the input is focused, the label is announced by screen readers. [### ✎ Technique: Icon fonts ](/technique-icon-fonts)Icon fonts are a popular and effective method for providing scalable symbols that can be used to label controls and provide graphical information. The information provided by icons also needs to be available to people who can’t see them.