@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

Decorator Pattern (Recommended)

The easiest way to use Emotion with Webflow code components is through the decorator pattern. This eliminates the need to manually wrap your component with the provider.

Basic Usage with Decorator

import { declareComponent } from "@webflow/react";
import { emotionShadowDomDecorator } from "@webflow/emotion-utils";
import styled from "@emotion/styled";

const StyledButton = styled.button`
  background-color: #007bff;
  color: white;
  padding: 8px 16px;
`;

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

export default declareComponent(MyComponent, {
  name: "My Component",
  decorators: [emotionShadowDomDecorator],
});

Custom Decorator with Options

You can create a custom decorator with specific Emotion cache options:

import { declareComponent } from "@webflow/react";
import { createEmotionShadowDomDecorator } from "@webflow/emotion-utils";

const customDecorator = createEmotionShadowDomDecorator({
  cacheOptions: {
    key: "custom-key",
  },
});

export default declareComponent(MyComponent, {
  name: "My Component",
  decorators: [customDecorator],
});

Provider Component (Manual Approach)

If you prefer more control, you can manually use the EmotionCacheShadowDomProvider component.

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",
  // Other Emotion cache options...
};

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

API Reference

emotionShadowDomDecorator

A decorator function that wraps a component with EmotionCacheShadowDomProvider.

Type:

<P extends {}>(Component: React.ComponentType<P>) => React.ComponentType<P>;

Example:

import { emotionShadowDomDecorator } from "@webflow/emotion-utils";

const decorators = [emotionShadowDomDecorator];

createEmotionShadowDomDecorator

Creates a custom decorator with specific Emotion cache options.

Type:

(options?: EmotionDecoratorOptions) =>
  <P extends {}>(Component: React.ComponentType<P>) =>
    React.ComponentType<P>;

Parameters:

• options (optional): Configuration options for the decorator
  • options.cacheOptions (optional): Custom options to pass to Emotion's createCache function

Example:

import { createEmotionShadowDomDecorator } from "@webflow/emotion-utils";

const customDecorator = createEmotionShadowDomDecorator({
  cacheOptions: {
    key: "my-app",
  },
});

EmotionCacheShadowDomProvider

A React component that provides Emotion cache configured for Shadow DOM.

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";
  // container is automatically determined based on DOM context
}

Why Shadow DOM Support?

Webflow code components run inside a Shadow DOM boundary. CSS-in-JS libraries like Emotion normally inject styles into the document head, but those styles aren't accessible inside the Shadow DOM. This package ensures styles are injected into the correct location within the Shadow DOM.

License

MIT