Search

    Shadow DOM

    Developer resources for working inside a Shadow DOM.

    Introduction

    This page contains developer resources for using Forge within a shadow DOM. Using the shadow DOM allows developers to isolate their CSS styling rules from other rules present on the page.

    Forge is compatible with the shadow DOM, but there are aspects about working within a shadow DOM that your app should be aware of.

    Portals

    Portals provide a first-class way to render children into a DOM node that exists outside the DOM hierarchy of the parent component. Forge uses portals in Lightbox, Modal and Toast for its content sit "above" everything. These portals are created on document.body by Forge's Root component. If a shadow root is detected above Forge's Root component, then a new shadow DOM is created in the portal, and all styling is copied from the original shadow DOM to the new shadow DOM. Any styles created by emotion-js are cloned there as well.

    If your app uses Emotion as well, or needs to create its own portal to document.body, then wrapping your component in withPortalData or withPortalDataAndRef will re-use Forge's EmotionCache and provide your component a portalData prop. You can create a portal to portalData.portalNode to portal close to document.body while still retaining all styling. Alternatively, Forge's Portal component can be used to portal to this DOM node.

    Emotion-js

    Emotion is a library designed for writing css styles with JavaScript. It provides powerful and predictable style composition in addition to a great developer experience with features such as source maps, labels, and testing utilities. Both string and object styles are supported.

    Forge uses uses react-select in Emotion in its Multiselect and SingleSelect components, which in turn uses Emotion for styling. By default, Emotion attaches its <style> tags to document.body, which gets ignored by the shadow root. To address this, Forge's Root component creates its own CacheProvider to cause Emotion styles to be amended to the shadow root instead. Multiselect then uses a higher order component, withPortalDataAndRef, to delay rendering Multiselect until after the existence of a shadow root can be detected.

    Resources