@webflow/react

The core React integration package for building Webflow code components. This package provides the essential tools for declaring components, rendering them on both client and server, and accessing Webflow-specific context.

Installation

npm i @webflow/react

Peer Dependencies

This package requires the following peer dependencies:

npm i react react-dom

Usage

Declaring Components

Use declareComponent to create a Webflow code component definition. This should be the default export from your *.webflow.tsx file.

Basic Example

import { declareComponent } from "@webflow/react";
import { props } from "@webflow/data-types";

function Button({ text, link }) {
  return (
    <a href={link?.href} target={link?.target}>
      {text}
    </a>
  );
}

export default declareComponent(Button, {
  name: "Button",
  description: "A customizable button component",
  props: {
    text: props.Text({ name: "Text", defaultValue: "Click me" }),
    link: props.Link({ name: "Link" }),
  },
});

With Decorators

Decorators allow you to wrap your component with additional functionality, such as CSS-in-JS providers:

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

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

With Options

export default declareComponent(MyComponent, {
  name: "My Component",
  props: {
    // ... your props
  },
  options: {
    applyTagSelectors: true, // Provide styles targeting tag selectors (default: false)
    ssr: true, // Enable server-side rendering (default: true)
  },
});

Using Webflow Context

Access Webflow-specific context data in your components using the useWebflowContext hook:

import { useWebflowContext } from "@webflow/react";

function MyComponent() {
  const { mode, interactive, locale } = useWebflowContext();

  return (
    <div>
      <p>Mode: {mode}</p>
      <p>Interactive: {interactive ? "Yes" : "No"}</p>
      <p>Locale: {locale}</p>
    </div>
  );
}

Context Properties:

• mode - The current mode ("design" or "preview")
• interactive - Whether the component is in an interactive state
• locale - The current locale (e.g., "en-US")

Server-Side Rendering

This package provides a server-side renderer for React components. The ServerRenderer provides:

• Server-side rendering with renderToString and renderToStream
• Support for creating slot elements with createSlot
• Automatic handling of Webflow context during SSR

Note: For CSS-in-JS libraries like Emotion or styled-components, use their respective server renderers instead:

• @webflow/emotion-utils/server
• @webflow/styled-components-utils/server

Configure the server renderer in your webflow.json file:

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

API Reference

declareComponent

Creates a Webflow code component definition.

Type:

<P extends {}>(
  Component: React.ComponentType<P>,
  data: ComponentData<P, React.ReactNode, React.ComponentType<P>>,
) => ComponentDefinition<React.ComponentType<P>, React.ReactNode, P>;

Parameters:

• Component - The React component to render
• data - Component metadata and configuration
  • data.name - The display name of the component
  • data.description (optional) - Description of the component
  • data.group (optional) - Group for organizing components
  • data.props (optional) - Component props configuration
  • data.options (optional) - Additional options
    • data.options.applyTagSelectors (optional) - Provide tag selector styles (default: false)
    • data.options.ssr (optional) - Enable server-side rendering (default: true)
  • data.decorators (optional) - Array of decorator functions

Returns: A Webflow code component definition

useWebflowContext

Hook to access Webflow context data.

Type:

() => WebflowContextType;

Returns:

{
  mode: "design" | "preview";
  interactive: boolean;
  locale: string;
}

ClientRenderer

A factory that creates a client-side renderer for a React component.

Type:

ComponentClientRendererFactory<
  React.ComponentType<ComponentRuntimeProps<React.ReactNode>>,
  ReactDOM.Root,
  React.ReactNode
>;

Methods:

• mount(domNode) - Creates a React root on the provided DOM node
• hydrate(domNode, props?, options?) - Hydrates a server-rendered component
• render(root, props?, options?) - Renders the component to an existing root
• createSlot(name) - Creates a named slot element for component composition

ServerRenderer

A factory that creates a server-side renderer for a React component.

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
• createElement(props?, options?) - Creates a React element with the component
• createSlot(name) - Creates a named slot element for component composition

applyDecorators

Utility function to apply an array of decorators to a component.

Type:

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

License

MIT