Skip to main content

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

Form elements

Updated on February 2, 2021

Form elements are essential components found throughout web applications. They are necessary building blocks used to drive data capture and configuration. Pega provides many form elements out of the box that can be used in your application.


Use a checkbox for binary selections (yes/no; true/false; etc) or to select many items in a list. Single checkboxes (binary) do not require an additional label, but should have a descriptive caption.

Multiple checkboxes (a checkbox list) do require a label and caption. Use a checkbox list when selecting many items in a list.


A different way of collecting binary information is a “switch” or “toggle”. Generally, toggles should be used:

  • As a setting control
  • On mobile
  • Not in a form
Note: There is no “undefined” state for a switch. If you have a requirement for an undefined option, you should choose a different control.

Date and time

Input field

Use a calendar picker when the expected date is within a few months of the current date. If possible, the ability to type directly into the field should be used as well.

Allow users to type directly into a date field when they are entering a date that is memorized (like a birthday), or is not close to the current date. (See more about this in the validation section below)

Do not use dropdowns for date entry. They are unnecessarily complex for most use cases.

If collecting a date range, the input for each should be the same type (calendar or direct type). The start and end dates should be directly subsequent to each other in the user’s tab order.

Set default dates inside inputs when it is obvious. Do not set a default if users are expected to change it most of the time. Usually, defaulting works best when the date is defaulted to the current date.

Validation and data masking

Date fields should be forgiving of many different ways of entering data. E.g. 12/31/17, 12-31-17, 12/31/2017, and 12 31 17 should all be accepted.

If the user has entered invalid data, the error message should include the preferred format. Pega’s preferred entry format is “MM/DD/YY”, or what is appropriate for the region (see notes about internationalization for read-only dates).

Inputs should be masked to the correct formatting when possible.

Read only

Clear dates and times help users create a mental model of time. There are two main use cases for using a date/time:

  • To give an idea of relative time to and from an event. (Called “common” time below)
  • To provide exact time
Common time

Use common times when the user needs to get a general idea of when something happened (or will happen). Most use cases for date/time in Pega applications fall in this category. Examples include chat, social, and general update times.

Time to displayPastFuture
Under a minuteJust now3:10pm
Under 1 hour1m ago - 59m ago3:10pm
This yearJan 15 or Jan 15 at 8:53pmDec 23 or Dec 23 at 3:10pm
Other yearsJan 15, 2017 or Jan 15, 2017 at 8:53pmDec 23, 2019 or Dec 23, 2019 at 3:10pm
Exact time

Use exact times when exact timestamps are important. These are more technical and should be used in more technical contexts. If using exact time, always include both date and time. Examples for this include audits, history, and additional information on common times.

Less precision12/31/2017 2:13pmCalendars, events, time/date hover. This should be internationalized & shown in local timezone.
Medium precision2017-12-31 14:13:30Audits/history. Shown in local time zone.
Most precision2017-12-31T22:30+04Extreme performance measuring. Uses ISO-8601 standard. Shown with UTC notation.

Common times should be shown in the user’s current time zone. The order of dates and months should be valid for that region. Use of 12 hour or 24 hour clock should also be valid for that region.

Exact times should be shown uniformly across an application. If the application will have an international audience, use the ISO-8601 standard (Y-M-D). If the application is meant for one region, use the appropriate layout for that region (M/D/Y for USA; D/M/Y for most).

At Pega, if the application is for no particular region, we use the American standards (shown) as a sample.

Drop down

Use a dropdown when there are 7+ options the user is selecting, and/or the options are dynamic and may change.

Combo boxes combine the functionality of a select box and an autocomplete/type ahead — these are the preferred control.

If specific native OS interaction is required, use a traditional select box.

Radio button group

Radio buttons should be arranged to stack vertically.

Radio buttons should have 2-7 static options.

If you require more than 7 options or if the options dynamically change, consider a multi-select or combobox.

Text inputs

Text area

Text area controls are used to capture free-form text from a user. Use this when collecting 2+ lines of text. Text areas generally stretch across the entire form. If text styling is necessary, use a rich text editor.

Text input

Text inputs are one of the most common ways of collecting form information. Use a text input whenever a user needs to enter free-form information.

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