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

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 |

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