Skip to main content

Accessible forms

One of the most of important parts of creating an application by using Pega Platform™ is creating forms. Forms are a critical component in most Pega applications. Forms are what we use to collect information from users, for whom we can then drive many different processes within an organization.

When creating forms, ensure that you choose the right components and configure them for optimal accessibility. This topic provides configuration recommendations and considerations, as well as a review of the components that are recommended from an accessibility standpoint, including:

  • Form and component options
  • Labels and captions
  • Helper text and placeholders

Form components

Form components are reusable UI elements with which users can input data into an application or perform a certain action. Numerous types of form components exist in Pega Platform as controls, each with their own unique functionality and purpose. Designing your app with proper form components in your UI creates an efficient application experience that is accessible to all users.

The following figure shows a simple form made of several form components:

A form consisting of text input fields and a group of radio buttons


The following table lists the form components that are recommended for use when you create an accessible application. These components provide appropriate keyboard navigation, screen reader navigation and overall ease of use and efficiency.

Form Component Recommendations
Component Recommended Use Keyboard Navigation Configuration Guidance
Autocomplete When a required selection is from a defined list and the list of options is lengthy. On focus, begin entering text for a list of options to be displayed and/or announced. No helper text or placeholder text.
Button When an action is needed to be triggered, for example, Submit or Cancel. On focus, press Enter to trigger the button action. Create the button label as text, not a graphic. Check the contrast of the text color against the background color.  
Checkbox When a single selection affirmation is needed or multiple selections are needed from a list of no more than 7. On focus, press Tab to cycle through the options and press the Spacebar to select the option. Set the checkbox UI label and place it to the right of the checkbox.
Date Time drop-down list When a simple date selection option is needed. Users select the month, day and year. On focus, press Enter to display and announce options. Navigate the options with the Arrow keys and select an option by pressing Enter. Use the full name of the month and include a default date, if possible.
Date Time Calendar

For Pega Platform version 8.8 and later, when a calendar is needed as a reference point for days of the week etc.  

Press Enter to open the calendar. Press Tab to navigate to a years and months spinner, and press Enter to select dates. Navigate through the days by pressing Tab and then press Enter to select a day. In versions of Pega Platform earlier than version 8.8, visible focus is not evident in the calendar, however, users can enter the date directly.
Drop-down list When a selection needed is from a defined list of more than 7 options On focus, press Enter to display and announce options. Navigate options with the Arrow keys and make selections by pressing Enter. Set placeholder text.
Icon When a visual symbol is needed to depict an idea, object, or action. Should not be interactive.

Do not use the same name and the same destination for an icon and link pair. If an interactive element is needed, it is better to use a button.

Link When you need to move users to a new URL, other location, or to a new position on the current page. On focus, press Enter to trigger the move to the new content. Be explicit. Do not use generic labels such as "Click here".
Radio buttons When you need users to select one option from a set of options. Press Tab to move to the first radio button. Navigate through other radio buttons by pressing the Arrow keys. Select a radio button by pressing the Spacebar. Radio buttons are not recommended for use within tables.
Rich Text Editor When you need to collect free-form text and images from the user, and give the user the option to style their input. Navigation is primarily through CK Editor shortcuts. Access the RTE toolbar (Alt+F10). Exit the input area (Esc+Tab).  
Text input When there is a need for users to enter and edit a single line of free-form text. On focus, add input.  

When building a form in a Pega application that provides an effective and efficient user experience, try to use the simplest and most practical components.

For more information on configuring components by Pega version, see Best practices for configuring accessible UI components on the Pega Documentation site.

Labels and captions


Labels are the text accompanying the field elements and describe the purpose and function of the form component with which they correspond. 

Clearly defined labels help users to complete their tasks confidently and with minimal chance of error. For users with varying cognitive abilities or users with different primary languages, this is especially true. Vague or ambiguous labels can lead to user confusion about how to complete a task, or make the user unsure of what information they must enter. 

When authoring your UI in Pega, provide a single label with each and every form component that you use. Labels are programmatically tied to a field once configured, and are displayed directly above the configured field. This means that sighted users can recognize the purpose of the field, as well as assistive technology users, whose software analyzes the underlying page markup to announce this information back to the user.

Best Practices

  • Always provide a label to all form components, even those within a table grid
  • Always use descriptive text for labels rather than technical terms to maximize comprehension
  • Keep the language of the label or caption simple and concise to clearly relay purpose and meaning

Configuring labels: 

The label of a component can be configured and edited in a section rule, as shown in the following figure:

Configuring a label in the section editor

The next figure shows how the label appears in the UI at runtime:


A label appearing above a configured field at runtime



      Captions function similarly to labels but you apply them to interactive elements, such as buttons, tables, and links, rather than fields. A caption should explain the purpose of the control it is configured on, and should be descriptive and user-friendly.

      Links also make use of captions, which are displayed visually as the actual link text. When creating a caption for a link, avoid using vague terms such as "Click here," or "Go." Instead, write a simple caption that clearly defines where the link will take the user.

      The following figure shows two examples of link captions that are unhelpful or otherwise inappropriate, and a third example that uses good, helpful text:

      Two examples of link captions to avoid and one correctly captioned link


      Best Practices

      When writing labels and captions for your form components, ensure that the text is clear, simple, and provides the information your users need to perform their tasks efficiently. Other best practices include:

      • Provide a caption for all applicable form components.
      • Keep the wording descriptive and user-friendly.
      • Avoid using technical terms, URLs, and vague instructions in caption text


      Helper Text and placeholders

      Helper text

      Sometimes, just having a label on a field is still insufficient for users to understand what action they need to take on that field. Adding additional informational text can be helpful for those with learning disabilities, impaired cognitive abilities, or those users for whom the language of the application is not their native language. Helper text serves as a method of providing further contextual information for all users.

      Pega Platform™ offers several helper text options for fields that you can use when building your UI. However, each type of helper text is different in terms of both user interaction and how accessible it is. The following table lists the most accessible helper text options and how you can best use them:

      Helper Text Recommendations
      Options Recommended Use Configuration
      Visible inline text  Best used on form components for additional assistance Always visible
      Helper icon on focus
      (Pega Platform version 8.8 and later)
      Best used on form components for additional assistance Do not use helper icon on hover
      Smart tip on focus Best used on buttons or icons for additional context Select plain text

        For a more detailed look at helper text options, see the Accessible Helper Text Options article in Pega Documentation.

        Best Practices

        Regardless of the helper text option that you choose for your components, the following guidance will help ensure that your helper text is informative and clear:

        • Not all fields require helper text. Use it when the information provided by the label may not be enough to understanding the field.
        • Ensure that the helper text on a field does not simply copy the label text
        • The helper text should clarify the purpose of the field
        • The helper text must be accessible to all users without interrupting the flow of the form or page
        • The helper text should help to reduce user input errors and mistakes

        Placeholder text

        Placeholders are a short word or phrase that describes the expected value of an input field. They can be configured on any form field in a Pega application, and appear as lighter-colored text in the input region of your field.

        Placeholder text should not be used as a substitute for a form component's label. It also should not restate what is already present in the label. Avoid applying placeholder text to many of your UI components, as it is not broadly supported across all assistive technologies and is not optimal for users with visibility or memory challenges. This is because of the low contrast of the text color against the background color, as well as the text disappearing when the user starts entering values in that field. 

        Best Practices

        • Avoid using placeholder text in most scenarios. Instead, opt for alternatives, such as helper text
        • If you use placeholder text, avoid placing large amounts of instructions in a placeholder.
        • Keep placeholder text short and concise


        Check your knowledge with the following interaction:

        This Topic is available in the following Module:

        If you are having problems with your training, please review the Pega Academy Support FAQs.

        Did you find this content helpful?

        Want to help us improve this content?

        We'd prefer it if you saw us at our best.

        Pega Academy has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

        Close Deprecation Notice