Define a code component

A code component definition is a file that tells Webflow how to use your React component on the Webflow canvas. It defines which properties designers can configure and how they’ll appear in the designer.

Every code component definition is a .webflow.tsx file that uses the declareComponent function to define the component.

1
import { declareComponent } from '@webflow/react';
2
import { props } from '@webflow/data-types';
3
import { Button } from './Button';
4
5
// Declare the component
6
export default declareComponent(Button, {
7
8
  // Component metadata
9
  name: "Button",
10
  description: "A button component with a text and a style variant",
11
  group: "Interactive",
12
13
  // Prop definitions
14
  props: {
15
    text: props.Text({ 
16
        name: "Button Text",
17
        defaultValue: "Click me"
18
    }),
19
    variant: props.Variant({ 
20
        name: "Style", 
21
        options: ["primary", "secondary"],
22
        defaultValue: "primary"
23
    }),
24
  },
25
  // Optional configuration
26
  options: {
27
    applyTagSelectors: true,
28
  },
29
});

File structure and naming

Code component definition files follow specific extension and naming patterns:

• File extension: .webflow.tsx or .webflow.ts
• Naming pattern: ComponentName.webflow.tsx (where ComponentName matches your React component)
• Location: Typically alongside your React component file

If you have specific naming needs, you can configure this pattern in webflow.json. It’s recommended to create your code component file alongside your React component, adding .webflow to the name. For example, Button.webflow.tsx for Button.tsx.

Imports

Every code component definition file needs to import your React component, Webflow functions, and any styles you want to apply to the component.

1
import { declareComponent } from '@webflow/react';
2
import { props } from '@webflow/data-types';
3
import { Button } from './Button';

Declare component

The declareComponent function creates a code component definition. It takes two arguments: the React component and a configuration object.

1
import { declareComponent } from '@webflow/react';
2
import { Button } from './Button';
3
import { styledComponentsShadowDomDecorator } from "@webflow/styled-components-utils";
4
import { props } from '@webflow/data-types';
5
6
// Declare the component
7
export default declareComponent(Button, {
8
9
  // Component metadata
10
  name: "Button",
11
  description: "A button component with a text and a style variant",
12
  group: "Interactive",
13
  decorators: [styledComponentsShadowDomDecorator],
14
  props: {
15
    text: props.Text({
16
      name: "Button Text",
17
      defaultValue: "Click me"
18
    }),
19
  },
20
});

• name: The name designers see in the component panel
• description?: Description to provide context for the component’s purpose (optional)
• group?: Organize components into groups in the component panel (optional)
• props?: Object defining the props of the component (optional)
• decorators?: Array of decorators to apply to the component (optional)
• options?: Object defining the options of the component (optional)

Prop definitions

The props object defines which properties of your React component a designer can edit in Webflow. Declare a prop for each editable property in your React component and provide metadata that will appear in the designer. To see a list of all available prop types and their configuration options, see the prop types reference. →

The below examples show a React component, its corresponding code component definition file, and how it appears in Webflow.

1
import React from 'react';
2
import styles from './Button.module.css';
3
4
interface ButtonProps {
5
  text: string;
6
  variant: 'primary' | 'secondary';
7
}
8
9
export const Button: React.FC<ButtonProps> = ({ text, variant }) => {
10
  return (
11
    <button 
12
      className={`${styles.button} ${styles[variant]}`}
13
      type="button"
14
    >
15
      {text}
16
    </button>
17
  );
18
}; 

See more examples in the prop types reference. →

Component decorators

Decorators are functions that wrap your React component with providers or other wrapper components. Use them to provide context like themes, internationalization, or feature flags, or to integrate CSS-in-JS libraries. For CSS-in-JS setup, see the frameworks and libraries guide.

Global styles

To apply global styles across all components, import your CSS in a global decorators file and reference it in webflow.json:

1
import "./globals.css";

1
{
2
  "library": {
3
    "globals": "./src/globals.ts"
4
  }
5
}

Custom decorators

Create a custom decorator when you need to wrap components with additional behavior. A decorator is a higher-order component that takes a component and returns a wrapped version. This example wraps a data-fetching component with an error boundary to handle API failures gracefully:

1
// Custom error boundary component that catches JavaScript errors in child components and displays a fallback UI
2
3
import React, { Component, ErrorInfo, ReactNode } from "react";
4
5
interface Props {
6
  children: ReactNode;
7
}
8
9
interface State {
10
  hasError: boolean;
11
}
12
13
// Catches JavaScript errors in child components and displays a fallback UI
14
class ErrorBoundary extends Component<Props, State> {
15
  state: State = { hasError: false };
16
17
  static getDerivedStateFromError(): State {
18
    return { hasError: true };
19
  }
20
21
  componentDidCatch(error: Error, info: ErrorInfo) {
22
    console.error("Component error:", error, info);
23
  }
24
25
  render() {
26
    if (this.state.hasError) {
27
      return <div>Something went wrong. Please refresh the page.</div>;
28
    }
29
    return this.props.children;
30
  }
31
}
32
33
// Decorator that wraps any component with error handling
34
export const errorBoundaryDecorator = <P extends object>(
35
  Component: React.ComponentType<P>
36
): React.ComponentType<P> => {
37
  return (props: P) => (
38
    <ErrorBoundary>
39
      <Component {...props} />
40
    </ErrorBoundary>
41
  );
42
};

To apply decorators globally, export a decorators array from your decorators file:

1
import "./globals.css";
2
import { errorBoundaryDecorator } from "./ErrorBoundary";
3
4
export const decorators = [errorBoundaryDecorator];

Options

The options object is used to configure the component for more advanced use cases. Options accepts the following properties:

Tag selectors

Styles targeting a tag selector (for example, h1, p, button) can be automatically provided to the Shadow DOM with the applyTagSelectors option. This is helpful for styling components with CSS selectors.

See more about styling components in the styling documentation. →

Server-side rendering (SSR)

By default, Webflow will load your component on the server. This means that the component will be rendered on the server, but the DOM will be hydrated on the client-side. This is helpful for improving the performance of your component.

You can disable this behavior by setting ssr to false.

Best practices

1
import "./globals.css";

1
{
2
  "library": {
3
    "globals": "./src/globals.ts"
4
  }
5
}

Next steps

Now that you understand code component definitions, you can:

• Understand styling - Learn about how to style your components.
• Explore prop types - Learn about all available prop types
• Configure bundling - Set up your build process
• Importing your components - Share your components with designers and other developers