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
// import '../styles/global.css'; // Import global styles
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
14
  // Prop definitions
15
  props: {
16
    text: props.Text({ 
17
        name: "Button Text",
18
        defaultValue: "Click me"
19
    }),
20
    variant: props.Variant({ 
21
        name: "Style", 
22
        options: ["primary", "secondary"],
23
        defaultValue: "primary"
24
    }),
25
  },
26
  // Optional configuration
27
  options: {
28
    applyTagSelectors: true,
29
  },
30
});

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';
4
// import '../styles/global.css'; // Import global styles

Declare component

The declareComponent function is used to create a code component definition. It takes two arguments:

• The React component
• An object with: Component metadata, prop definitions, and optional configuration

Component metadata

The metadata properties define how your component appears in the Webflow designer:

1
import { declareComponent } from '@webflow/react';
2
import { Button } from './Button';
3
// import '../styles/global.css'; // Import global styles
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
});

• 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)

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. →

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

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