@webflow/emotion-utils

@webflow/emotion-utils

A React utility package for working with Emotion CSS-in-JS in Shadow DOM environments. This package exposes a provider component that automatically configures Emotion's cache to work correctly within Shadow DOM boundaries.

Installation

npm i @webflow/emotion-utils

Peer Dependencies

This package requires the following peer dependencies:

npm i @emotion/cache @emotion/react react react-dom

Usage

EmotionCacheShadowDomProvider

The EmotionCacheShadowDomProvider component automatically detects whether it's running inside a Shadow DOM and configures Emotion's cache accordingly. When inside a Shadow DOM, it injects styles into the Shadow Root; otherwise, it falls back to the document head.

Basic Usage

import React from "react";
import { EmotionCacheShadowDomProvider } from "@webflow/emotion-utils";
import styled from "@emotion/styled";

const StyledButton = styled.button`
  background-color: #007bff;
`;

function MyComponent() {
  return (
    <EmotionCacheShadowDomProvider>
      <StyledButton>Click me!</StyledButton>
    </EmotionCacheShadowDomProvider>
  );
}

With Custom Cache Options

You can customize the Emotion cache by passing options to the provider:

import React from "react";
import { EmotionCacheShadowDomProvider } from "@webflow/emotion-utils";
import type { Options as CreateCacheOptions } from "@emotion/cache";

const cacheOptions: CreateCacheOptions = {
  key: "my-custom-key",
  speedy: true,
  // Other Emotion cache options...
};

function MyApp() {
  return (
    <EmotionCacheShadowDomProvider options={cacheOptions}>
      {/* Your styled components */}
    </EmotionCacheShadowDomProvider>
  );
}

API Reference

EmotionCacheShadowDomProvider

Props

Prop	Type	Required	Description
children	React.ReactNode	Yes	The React components that will use Emotion styles
options	CreateCacheOptions	No	Custom options to pass to Emotion's createCache function

Default Cache Options

{
  key: "webflow",
  speedy: false,
  // container is automatically determined based on DOM context
}

License

MIT