Form elements

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.

All form elements have various displayed states throughout the UI to help communicate interaction. Checkboxes, radio buttons, switches are used in different instances but follow similar patterns of interaction.

Button statesPurpose
Enabled stateCommunicates an interactive button, a button is in this state the majority of the time.
Hover stateCommunicates when a user has placed a cursor above a button.
Active stateCommunicates when a user has clicked into the button or activated it through keyboard or voice commands.
Focus stateCommunicates when a user has highlighted an element, using an input method such as a keyboard or voice.
Disabled stateCommunicates a non-interactive action, usually shown in error states or when waiting for a user to enter in information prior to moving on with the workflow.

Last updated: Dec 2019

Text inputs

Text inputs fields allow users to enter and edit data.

The Pega Cosmos design system has various text input fields for different types of data collection needs.


The Auto-complete is a text input field component that allows a user to choose from a list of options combining the functionality of a select box and an auto-complete (aka. type ahead, or auto-suggest).

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

combo box text input

Date picker

Date pickers enable users to select a single or a range of dates.

date picker text input

Use a date picker when the expected date is within a few months of the current date. Allow users to type directly into a date field when they are entering a date that is memorized, such as 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). Read more.

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

For more on designing for an international audience, read about Internationalization in Language.


A multi-select input field is a hybrid of a select and search field, making this type of component useful for content such as tagging, contact lists.

multiselect text input

Number input

Number input fields allow users to enter a number within certain range using the top-down arrow control. Data input can be manipulated with either the mouse or keyboard.

number input text input


Use a select input field when there are 7+ options the user is selecting, and/or the options are dynamic and may change. If there are less than 7 options, a radio button or checkbox component may be more beneficial.

select text input


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

standard text input

Text area

Text area fields 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 utilizing the entirety of a one-column grid. If text styling is necessary, use a rich text editor.

text area text input

Last updated: Mar 2020


Checkboxes are used to present a list of options to a user, where they may select multiple options including all or none.



Use a checkbox for binary selections (yes or no; true or 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.

checkbox list


Checkboxes can be selected or unselected. Similarly to buttons, checkboxes have enabled, hover, focused, and active states.

checkbox specs

Last updated: Dec 2019

Radio buttons

Radio buttons allow a user to select one option from a collective set.

radio button select and unselect states

Use radio buttons when the user needs to see all available options and choose only one. This form of selection control should be arranged to stack vertically and should be limited to 2-7 static options.

radio button list

If you require more than 7 options or if the options dynamically change, consider a multi-select or combobox. If available options can be collapsed or hidden, consider using a dropdown input field.


Radio buttons can be selected or unselected. Similarly to buttons, radio buttons have enabled, hover, focused, and active states.

radio button specs

Last updated: Aug 2019