@webflow/styled-components-utils

A React utility package for working with styled-components in Shadow DOM environments. This package exposes a provider component that automatically configures styled-components to work correctly within Shadow DOM boundaries.

Installation

npm i @webflow/styled-components-utils

Peer Dependencies

This package requires the following peer dependencies:

npm i styled-components react react-dom

Usage

Decorator Pattern (Recommended)

The easiest way to use styled-components 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 { styledComponentsShadowDomDecorator } from "@webflow/styled-components-utils";
import styled from "styled-components";

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: [styledComponentsShadowDomDecorator],
});

Custom Decorator with Options

You can create a custom decorator with specific StyleSheetManager options:

import { declareComponent } from "@webflow/react";
import { createStyledComponentsShadowDomDecorator } from "@webflow/styled-components-utils";

const customDecorator = createStyledComponentsShadowDomDecorator({
  styleSheetOptions: {
    disableCSSOMInjection: false,
  },
});

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

Provider Component (Manual Approach)

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

Basic Usage

import React from "react";
import { StyledComponentsShadowDomProvider } from "@webflow/styled-components-utils";
import styled from "styled-components";

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

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

With Custom StyleSheetManager Options

You can customize the StyleSheetManager by passing options to the provider:

import React from "react";
import { StyledComponentsShadowDomProvider } from "@webflow/styled-components-utils";
import type { IStyleSheetManager } from "styled-components";

const styleSheetOptions: IStyleSheetManager = {
  namespace: "my-custom-namespace",
  disableCSSOMInjection: false,
  // Other StyleSheetManager options...
};

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

Server-Side Rendering

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

Using the Server Renderer

Configure the server renderer in your webflow.json file:

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

The ServerRenderer extends the base React server renderer and:

• Automatically wraps your component with styled-components' ServerStyleSheet
• Collects and extracts styles 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
}

Bundle Configuration

This package exports a bundle configuration override that optimizes styled-components for production builds.

Using the Bundle Config

Step 1: Create a webpack.webflow.js file in your library root:

const {
  styledComponentsBundleConfig,
} = require("@webflow/styled-components-utils");

module.exports = {
  ...styledComponentsBundleConfig,
};

Step 2: Reference it in your webflow.json file:

{
  "library": {
    "bundleConfig": "./webpack.webflow.js"
  }
}

The bundle config automatically:

• Adds the babel-plugin-styled-components to your build
• Enables SSR support (ssr: true)
• Includes file names in generated class names for better debugging (fileName: true)

This ensures consistent class names between server-side and client-side rendering, avoiding style hydration mismatches.

API Reference

styledComponentsShadowDomDecorator

A decorator function that wraps a component with StyledComponentsShadowDomProvider.

Type:

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

Example:

import { styledComponentsShadowDomDecorator } from "@webflow/styled-components-utils";

const decorators = [styledComponentsShadowDomDecorator];

createStyledComponentsShadowDomDecorator

Creates a custom decorator with specific StyleSheetManager options.

Type:

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

Parameters:

• options (optional): Configuration options for the decorator
  • options.styleSheetOptions (optional): Custom options to pass to styled-components' StyleSheetManager

Example:

import { createStyledComponentsShadowDomDecorator } from "@webflow/styled-components-utils";

const customDecorator = createStyledComponentsShadowDomDecorator({
  styleSheetOptions: {
    disableCSSOMInjection: false,
  },
});

StyledComponentsShadowDomProvider

A React component that provides StyleSheetManager configured for Shadow DOM.

Props

| Prop | Type | Required | Description | | ---------- | -------------------- | -------- | -------------------------------------------------------------- | | children | React.ReactNode | Yes | The React components that will use styled-components | | options | IStyleSheetManager | No | Custom options to pass to styled-components' StyleSheetManager |

ServerRenderer

A server-side renderer factory for styled-components. Available via @webflow/styled-components-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

styledComponentsBundleConfig

Bundle configuration overrides for optimizing styled-components builds.

Type:

BundleConfigOverrides;

Configuration:

• Adds babel-plugin-styled-components with SSR and fileName options enabled

Why Shadow DOM Support?

Webflow code components run inside a Shadow DOM boundary. CSS-in-JS libraries like styled-components 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