Documentation versions (currently viewingVaadin 24)

Application Themes for Embedded Components

Things to consider when using a custom theme for embedded applications.

It’s possible to embed an entire Vaadin application — parts of one or custom Flow-based components — into other web pages. The mechanism for doing so generates a custom Web Component that wraps the embedded UI inside its Shadow DOM. This has certain implications for theming, which are covered in more detail in the Theming Embedded Applications section.

There are a few related factors to consider. First, the @Theme annotation can be used to apply a theme to the embedded UI. It’s applied to the class extending the WebComponentExporter class.

Also, the applied theme is injected into the Shadow DOM of the wrapper Web Component. Because of this any CSS applied to the html or body root element selectors must also be applied to the :host() root selector of the embedded UI. Use the html, :host() selector if you want the styles to work both in embedded and non-embedded contexts.

Another thing to know is that the theme’s CSS must be divided into two stylesheets:

  • document.css: This should contain any CSS that needs to work in an overlay (e.g., a dialog), as well as @font-face declarations. These styles are loaded into the root of the parent page.

  • styles.css: This is where to place any CSS that should not be loaded into the parent page. You might not want to load these in case of conflicts with the parent page’s CSS.

Finally, you should be aware that Lumo Utility Classes don’t work in overlays in embedded UIs.