Skip to main content

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

Assigning WAI-ARIA roles to a Dynamic Layout

Updated on November 15, 2021
Applicable to Theme UI-Kit applications

Make your application more accessible to users with disabilities by adding semantic information about the role of a layout on a page. When you define the role of a layout in your UI, you provide screen reader users with the information that they require to successfully navigate your application.

When you develop your application, Pega Platform automatically assigns WAI-ARIA roles to the screen layout. Other layouts in the system do not have default accessibility roles when you create them. For most use cases, the blank setting is sufficient. However, when you design a layout that behaves in an unconventional way, you must assign a WAI-ARIA role to that layout by hand.

For example, your page might include a large layout that you can click. Because the default role for the layout is blank, a screen reader ignores the layout and does not inform the user that it can be clicked. If you assign a button role to the layout by hand, the screen reader can interpret the header correctly.

  1. In the navigation pane of Dev Studio, click Records.
  2. Expand the User Interface category, and then click Section.
  3. Open the section that you want to edit.
  4. If your section uses a template, in the section editor header, click convert to full section editor, and then confirm the conversion.
  5. Select the dynamic layout to which you want to assign a WAI-ARIA role, and then click the View properties icon.
    Note: Only dynamic layouts support WAI-ARIA roles.
  6. In the Accessibility section, in the Role type list, define the general role of the layout:
    • To mark a layout as a primary part of the page, such as a form, select Landmark.
    • To mark a layout as a structural, non-interactive part of the page, such as a header, select Document structure.
    • To mark a layout as an interactive part of the page, such as a link, select Component/Widget.
    For example: Select Component/Widget for access roles related to interactive elements.
  7. In the Value field, select the specific role for the layout.
    For example: Select Button to mark the layout as an element that you can click.
  8. In the Label field, provide a short, meaningful description of the content of the layout, and then click Submit.
    For example: Link to the home page.
  9. On the design template form, click Save.

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