Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Best practices for configuring UI components

Updated on December 13, 2022

Pega Platform UI components have different levels of out-of-the-box accessibility. By learning about best practices for configuring accessible behavior of UI elements such as controls and layouts, you can improve the user experience for customers who rely on assistive technologies.

Accessible UI components and configurations

The following table lists out-of-the-box accessibility of UI components and recommended configurations that improve their availability to users who are differently abled.

ComponentRecommended?ChallengesRecommended configuration
  • Incorrect role.
  • No state information.
  • Visual-only hover information.
Use a Dropdown.
  • Cannot support announcing grouped content.
  • Cannot support the Choose command in Dragon.
  • Wide results with multiple values clutter screen readers.
Set placeholder and helper text to None.
  • Set Button caption to Text.
  • Add an action that displays a smart tip in plain text on focus.
  • To reuse the smart tip, create a message in Dev Studio.
  • Keep the text distinct from the label.
  • Check the color contrast against the background.
ChartPartiallyGraphics are not accessible.
  • Include a checkbox for users to display wedge values and names.
  • Provide descriptions for labels.
  • Create a table as an alternative.
Checkbox Yes Issues with label display.
  • For read-only controls, use captions instead of labels.
  • Set captions to appear to the right of the checkbox.
  • Show caption value as text, not image.
Date TimePartially
  • No focus on the calendar icon.
  • Limited focus on calendar navigation.
  • Cannot provide a text input alternative.
  • Configure text input for the calendar.
  • Set helper text to be always visible and define the required date pattern in the text (for example, MM/DD/YYYY).
  • Configure navigation to use drop-downs.
Date Time: no typing No Cannot access by keyboard.Use a standard Date Time control.
Date Time: dropdown Partially Labels not visible.
Date Time: date rangeNo
  • Cannot access by keyboard
  • No labels on each individual drop-down list for month, day, and year
Use a standard Date Time control.
Date Time: time only No
  • Cannot access by keyboard.
  • No focus on apply and cancel actions.
Dropdown Yes
  • Set read-only value to display the text of the selected option.
  • Set a placeholder.
  • Check the placeholder text color for contrast.
Dynamic layoutYes
  • Use headers and titles.
  • Assign an ARIA role where appropriate.
Dynamic layout group Yes Navigated by using the Tab key.
  • Use headers and titles.
  • Do not create tables inside a Dynamic layout group.
Hierarchical table Yes Navigated by using the Tab key.
Hierarchical table (optimized) Yes
  • Do not use tables as layouts.
  • Avoid using interactive elements, such as links or buttons, inside tables.
Icon Yes
  • Set helper text to display a tooltip on hover.
  • Create an action that displays a smart tip when users press the Enter key.
  • Do not use the same name and the same destination for an icon and link pair.
Integer Yes
Layout groupYesFocus not always clear.For more information, see Supported keyboard navigation.
Link Yes Include helper text only if you need to add additional context to the link.
List Yes
  • Assign the list role to the section that holds the list.
  • Assign the items role to the items on the list.
Map Partially Cannot provide focus or keyboard access for some map features.
Modal dialog boxYes
Multi-select list Yes As an alternative, use a separate drop-down list.
Navigational treeNo Cannot access by keyboard.
Overlay Partially
  • Lengthy content difficult to scroll.
  • No focus.
  • Set helper text to none
  • If you need helper text, set an action that displays a smart tip on focus.

Radio buttonsYes Issues when used in a table.

Add a title and a heading.

Repeating dynamic layoutYes Navigated by arrow keys.For more information, see Supported keyboard navigation
Rich text editorYes
  • Support for CKEditor shortcuts only.
Disabling the mouse-only Resize option is a best practice.
SectionsYes Add ARIA roles.
Slider No Cannot access by keyboard.
Table (optimized) Yes
  • Difficulties navigating when using filters and sorting.
  • Navigated by using the Tab button.
  • Do not use tables as layouts.
  • Do not use tables inside repeating dynamic layouts.
  • Do not use interactive elements, such as links or buttons, inside tables.
Text areaYes
Text inputYes
  • Helper text overrides the label.
  • Inline field validation does not meet best practices.
  • Add a smart tip that appears on focus.
  • Do not use as a disabled field. Use read-only status instead.
Timeline No Cannot access by keyboard.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us