Skip to main content

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

Cosmos DX components in Cosmos React

Updated on May 27, 2022

While the Cosmos React architecture has an extensive library of out-of-the-box assets, the framework provides tools for expanding the UI by adding Cosmos digital experience (DX) components. This still-evolving framework helps early adopters build interfaces tailored to their specific business needs.

While using custom DX components in Cosmos React, keep in mind that it is an expanding product with a narrower feature set. Consequently, the framework might not support some classic Constellation features. You might also encounter unforeseen issues.

Note: This information is intended only for professional developers in advanced use cases where out-of-the-box components do not meet the users' needs. To create custom components, you need knowledge in Cosmos React development and common development tools such as NPM and Git.

Cosmos React is designed to address most enterprise design workflow needs through out-of-the-box assets. Low-code developers, business architects, and UX designers do not create Cosmos DX components in Cosmos React. For more information on working with out-of-the-box Cosmos assets, see Configuring Cosmos React.

To maintain a consistent, branded experience across channels, Cosmos React applications rely on the Pega Cosmos design system for styling. The goal of the Cosmos DX component toolkit aims to extend the library of existing Cosmos components and create new components that integrate seamlessly within the set of out-of-the-box components. You can use Cosmos DX components to expand Cosmos React in specific scenarios where out-of-the-box components might not meet immediate business needs.


Cosmos React supports customized components. The Cosmos DX components fit seamlessly into the out-of-the-box features of Cosmos. When creating your Pega Platform application, you use your own Cosmos DX components in the same way as you use the standard components. The style of your Cosmos DX components closely matches that of the out-of-the-box Cosmos React components.

You create, modify, and publish your own components by leveraging the Pega ConstellationJS APIs and the Cosmos React UI components library. Your components are available in App Studio alongside the out-of-the-box components.

Note: Unlike Cosmos DX components, you cannot modify the out-of-the-box Cosmos React components.

Development process

The development of custom components is a complex process that consists of several stages before the component is ready to use in your application. The development of custom components consists of the following steps:

  1. Importing the component and ConstellationJS API libraries.

    You download the libraries to your local machine to use in the creation process.

  2. Creating a component.

    You edit the template code generated by the framework to develop your custom field, layout template, or widget. You use generally available tools such as NPM and NodeJS to create your component.

  3. Publishing a component.

    You submit your component to Pega Platform along with the ruleset and version. Then, you export your components into App Studio.

For more information, see Life cycle of a Cosmos DX component.

Run-time behavior

Cosmos DX components use the ConstellationJS client run-time APIs in the same manner as out-of-the-box Cosmos React components. ConstellationJS automatically invokes the render function of the component when data that is associated with the component changes.


When you create a new component, the system adds a config.json component definition file to the folder of the component. You define the parameters for your components in the config.json file of each component. The JSON metadata defines the type of a parameter, for example, constant, property, or picklist. After you publish the component, App Studio uses the config.json metadata to generate a property pane for the component. The same config.json object is passed to the render function of the components together with App Studio developer settings and the data obtained from the run-time case information.

See the following articles to learn more about Custom DX Components:

  • Structure of a Cosmos DX component

    Learn about the structure of Cosmos digital experience (DX) components in an application. An organization can have several applications. Each application can use several customized components. For easier organization and maintenance, you can group components in libraries. The component libraries can be created in different rulesets, which in turn can be used for different applications.

  • Life cycle of a Cosmos DX component

    Learn to create and use a custom Cosmos digital experience (DX) component in your application. Understanding all steps of the process helps you successfully build and deploy custom components to adapt and extend the UI of your application.

  • Component definition

    The DX Component Builder generates a config.json file, or component definition file, when you create a component. This file drives the UI authoring experience when you configure the component for use in Pega Platform, meaning that the property pane of the component in Pega Platform is defined by this file.

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