@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>
  );
}

Server-Side Rendering

This package provides a server-side renderer that automatically handles Emotion SSR configuration.

Using the Server Renderer

Configure the server renderer in your webflow.json file:

{
  "library": {
    "renderer": {
      "server": "@webflow/emotion-utils/server"
    }
  }
}

The ServerRenderer extends the base React server renderer and:

• Automatically wraps your component with Emotion's CacheProvider
• Collects and extracts critical CSS during server-side rendering
• Returns both HTML and styles in the renderToString method

Return Type:

{
  html: string; // The rendered HTML
  styles: string; // The extracted style tags
}

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
}

ServerRenderer

A server-side renderer factory for Emotion. Available via @webflow/emotion-utils/server.

Type:

ComponentServerRendererFactory<
  React.ComponentType<ComponentRuntimeProps<React.ReactNode>>,
  PipeableStream,
  ReactDOMServer.RenderToPipeableStreamOptions,
  React.ReactNode,
  ReactDOMServer.ServerOptions
>;

Methods:

• renderToStream(props?, options?, streamOptions?) - Renders component to a pipeable stream
• renderToString(props?, options?, stringOptions?) - Renders component to a string with extracted styles
• createElement(props?, options?) - Creates a React element with the component
• createSlot(name) - Creates a named slot element for component composition

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