Accessibility - Configuring semantic heading levels

From PegaWiki
Accessibility - Configuring Semantic Headings in the Application / This is the approved revision of this page, as well as being the most recent.
Jump to navigation Jump to search

Accessibility - Configuring semantic heading levels

Description A guide to creating and using semantic heading levels in the User Interface
Version as of 8.4
Application Pega Platform
Capability/Industry Area User Experience

Accessibility - Configuring Semantic Headings in the Application
This article has been moved over to our Pega Community here in order to align with our larger content strategy. Please update any bookmarks or links that you may have to this location.

Headings in HTML serve a variety of purposes for all users. They can be used as navigation landmarks for screen readers, an organizational component for content, or they can act as a table of contents for a page. The use of semantic headings across the application is necessary for ensuring that users across browsers and assistive technologies have an equal and accessible experience in a web application.  

Configuring a heading in the section editor

When designing a section rule, headings do not exist as standalone reusable User Interface (UI) components that can be dragged or added in, but are instead part of the configuration options on a Dynamic Layout.

In any Dynamic Layout’s configuration dialog, a checkbox labeled “Display header and title” is left unchecked by default. Selecting this checkbox will generate a semantic heading element for your Dynamic Layout.  

Dynamic Layout configuration with the heading option selected
Dynamic Layout configuration with the heading option selected

Further configuration options for headings configured through a Dynamic Layout include:

  • Heading label - the textual value of the heading
  • Heading label source:
    • Text - plain text entered directly on the Dynamic Layout's configuration
    • Field Value - a reference to a field value
    • Property - a reference to a property
  • Heading level - the level (size) of the heading, from 1-6
  • The option to include an icon or value
  • Visibility Conditions
  • Header Type - style/functionality of the header

Markup implications

Using the Dynamic Layout configuration for headers is recommended, as it generates a semantic <h> heading element in the markup at runtime. Styling a label to appear visually as a heading element should be avoided, as the markup generated will not reflect a true semantic heading and can interfere with the workflow of users with assistive technologies.

One configuration option to watch out for is applying the role=”heading” attribute to the Dynamic Layout in which a heading has been configured. This attribute can be configured on container components when editing a section but is recommended not to be used on Dynamic Layouts that contain a heading.

The role configuration option for dynamic layouts, set to None
The role configuration option for dynamic layouts

This is because the role will be applied to all the contents within the Dynamic Layout, not just the header itself. Assistive technologies will be able to recognize and correctly interact with the semantic heading generated as is. If introducing this role is an application requirement, configuring a Dynamic Layout with no content other than the heading is a way to achieve this without introducing the attribute on undesired elements.

Accessible headings


To ensure that your configured headers are both accessible and semantically correct, there are a few points that are good to consider. Headings on a web page should be placed in a correct hierarchy, ranging from large (h1) to small (h6). This approach improves visual consistency and introduces consistency in the presentation of information and landmarks. Using the built-in Pega Accessibility Inspector, finding out-of-order headings is as simple as launching the inspector on the current page.

Assistive Technology Compatibility

Lastly, it is good to perform a test with assistive technologies such as a screen reader to ensure that the configured headings are recognized as semantically correct. Screen readers offer shortcuts to both navigate between and list out the headings on a page. For example, JAWS has shortcuts such as the “H” key or “Ins+F6” that help users to navigate to and list headings, respectively.

A JAWS dialog box listing all headings on the current page
A JAWS dialog box listing all headings on the current page


Semantically correct headings and markup are important not only visually, but also behind the scenes for all users of the application. A proper hierarchy of headings provides not only visual consistency, but also good organization of the content of your page under ordered landmarks. Following this configuration guide will make a positive impact to both the application and its users.