Conversation
Pegasystems Inc.
PL
Last activity: 7 Oct 2025 2:58 EDT
Advanced Constellation Web Embed Customization
Why
Seamless integration between existing enterprise web applications and Pega is key. Foundational article (https://support.pega.com/discussion/configuration-web-embed ) on web embed configuration established the authentication patterns and basic setup and best practices. Real-world implementations sometimes require sophisticated customization to meet specific business requirements and brand guidelines.
You might encounter three advanced use cases when implementing Constellation Web embed solutions.
-
First, you need to ensure visual consistency with their existing web properties, requiring some level of control over styling and branding elements.
-
Second, you must optimize the user experience by selectively displaying only relevant interface components, hiding unnecessary elements that might clutter or confuse the customer journey. While Pega Web Embed components keep getting better and allow for flexible configuration there might be some elements that you want to hide manually
-
Third, you require dynamic data flow between their parent applications and the embedded Pega content, enabling sophisticated state management and real-time interactions.
Before customizing
Constellation Web embed supports comprehensive styling customization through multiple approaches, each suited to different organizational needs and technical architectures. The most robust approach involves leveraging the theme attribute to pass custom design tokens that override default Pega styling.
For Pega Infinity 24.2 and above, leverage the themeID attribute for centralized theme management, referencing themes created in App Studio for better maintainability and governance. For use cases when styling with tokens in theme are not enough, custom css styling might be an option.
Disclaimer:
While this is technically possible to inject custom CSS to web embed this is not advised solution for the following reasons:
-
Web Embed styling is governed by Constellation Design System
-
Custom CSS styling approach quickly might become difficult to maintain
-
Constellation's DOM structure for a view or individual components may change with every hotfix or patch release. Leveraging CSS selectors reliant on specific sequences of elements may fail if there is such a change
Custom Css styling might be a good option for minor UI tweaks.
Custom CSS Styling Techniques – prior to Pega 25
Warning:
Inserting a style block with inline styles will cause CSP directives unsafe-inline unless a proper nonce is also associated with the style. Generation and verification of nonces are not described as part of this article.
Web Embed functionality relies on Shadow DOM (https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) which keeps outer page and DOM imported from Pega separated avoiding CSS and JS conflict. Code below outlines how to inject CSS to Web Embed:
Example above outlines how we can inject CSS styles in Shadow DOM make it possible to change styling of UI imported from Pega. Example is made in Vite+React application, you would need to adjust this implementation according to tech stack of you portal hosting Web Embed. Key information is to utilize embedready event, implemenation of passing CSS to Shadow DOM might vary. PegaStyle mentioned in above snippet might look like CSS example below. This CSS snippet styles Cancel button.
Element Hiding and Interface Optimization
Selective element hiding is crucial for creating focused user experiences that align with specific business processes. The web embed content can be precisely controlled using CSS selectors that target specific DOM elements generated by the Constellation UI.
Here are proven techniques for hiding some interface elements:
These selectors target specific parts of the Constellation UI structure. The key principle is to inspect the generated DOM using browser developer tools to identify the exact elements you want to hide, then create specific CSS rules that target those elements without affecting the functional components.
For dynamic elements hiding based on user context or application state, combine CSS with JavaScript event listeners and conditionally apply or remove CSS classes.
Custom CSS Styling Techniques – Pega 25
Starting with Pega 25 Web Embed configuration takes additional parameter supports a customCSS attribute to easily refer to an external file resource that would contain CSS and be seamlessly injected into the shadowDOM to affect pega-embed's Constellation styling. Read more about customCSS attribute in official documentation: https://docs.pega.com/bundle/platform/page/platform/user-experience/branding-web-embeds.html
Data Passing and Redux Integration
Integrating external application state with embedded Pega content requires careful orchestration of data flow and event handling. The web embed supports bidirectional communication through custom attributes and event listeners that can interface with modern state management libraries like Redux.
Here's a comprehensive approach to Redux integration.
This pattern ensures that your embedded Pega application has access to the necessary context data while maintaining clean separation of concerns between the parent application and the embedded content.
Other use cases
There are other typical use cases that you might want to explore
-
Passing starting fields so your case processing can be influenced by state of external application
-
Passing custom headers for authentication purposes
Reach out to documentation listed below.
References
This article builds upon the comprehensive foundation established in the Configuration of Web Embed discussion, which provides essential background on authentication patterns and basic setup procedures.
For detailed technical documentation on Constellation Web embed capabilities, consult the following official Pega resources:
-
Embedding Constellation UI in web pages - Comprehensive technical documentation covering web embed implementation and configuration options.
-
Extending Constellation applications - Advanced integration patterns and extension methodologies for Constellation applications.
-
Web embed attributes - Complete reference for all available web embed attributes and their usage patterns.
-
Events in web embed - Documentation on event handling and bidirectional communication patterns.
Additional resources for advanced implementation scenarios include the Constellation web embed module on Pega Academy, which provides hands-on exercises and real-world implementation examples that complement the techniques described in this article.
The sample code implementation using Vite, React, and Pega Web Embed that you provided demonstrates these concepts in a practical context, showing how modern JavaScript frameworks can be effectively integrated with Pega's Constellation architecture to create sophisticated enterprise applications.