Skip to content
Skip to main contentWhere does your team stand on AI adoption?
CONTACT SALESSTART BUILDING

Components with state

Pass data from Builder or from your application directly to your custom component to customize styles or behaviors.

What to know

  • Inputs to custom components in Builder are accessible to the component code through the component's props.
  • Access dynamic values in Builder state within a custom component through the builderState property.
  • Pass data from your application directly into Builder state with the data attribute.

Access custom component options

When a custom component is provided an input option, that value can be accessed directly within the component through props. This value is defined in code, but can be manipulated in Builder's Visual Editor.

Framework
Meta-Framework
SDK Generation

For example, the custom component below, CustomTip, accepts a single input called text.

import { Builder } from "@builder.io/react"; Builder.registerComponent(CustomTip, { name: "CustomTip", inputs: [ { name: "text", type: "text", defaultValue: "Hello, Builder!", required: true, }, ], });

Access the value within the custom component by referencing the value directly within props.

// CustomTip.tsx interface CustomTipProps { text: string; } const CustomTip = (props: CustomTipProps) => { return ( <div className="custom-tip"> <h2>Tip</h2> <p>{props.text}</p> </div> ); }; export default CustomTip;

Within the Visual Editor, you can set the value by clicking on the component and then going to the Options panel. There, change the input's value.

In the video below, the Options panel contains the text state value. When updated, the text within the CustomTip component is updated on the page.

Access custom component state

By creating a custom input, you add user-defined state to a custom component within the Visual Editor. Your custom component will have access to that value as well.

In the video below, a new custom input is created within the Content Inputs panel called calloutText. This input is given a default value of "Tip".

Framework
Meta-Framework
SDK Generation

Within your custom component, access the calloutText value by accessing builderState.

interface CustomTipProps { builderState: { state: { calloutText: string; } }; text: string; } const CustomTip = (props: CustomTipProps) => { const callout = props.builderState.state.calloutText || "Tip"; return ( <div className="custom-tip"> <h2>{callout}</h2> <p>{props.text}</p> </div> ); }; export default CustomTip;

This value can be changed within the Data tab under Content State.

In the video below, the calloutText value is changed from "Tip" to "Helpful hint." This changes the display of the custom component.

Access application state in a custom component

You may also access application state within your custom components. This can be useful, for example, when you want to be able to influence the presentation of a component based on internal values within your application.

Framework
Meta-Framework
SDK Generation

When the BuilderComponent below is rendered, the data attribute is set to an object which contains a key called theme and points towards a value that is set by state.

import { Builder, BuilderComponent } from "@builder.io/react"; import { useState } from "react"; import CustomTip from "../components/CustomTip"; // Register your custom component Builder.registerComponent(CustomTip, { name: "CustomTip", // ... }); // Pass data into the component function CustomComponent() { const [content, setContent] = useState<any>(null); const [theme, setTheme] = useState("dark"); // ... Request data and set the content and theme. return ( <BuilderComponent content={content} model={BUILDER_MODEL} data={{ theme: theme, }} /> ); } export default CustomComponent;

A special property is added to your props, called builderState. This will include state values provided by you in the application and other state values provided to Builder.

interface CustomTipProps { builderState: { state: { calloutText: string; theme: string } }; text: string; } const CustomTip = (props: CustomTipProps) => { return ( <div className={`custom-tip ${props.builderState.state.theme}`}> <h2>{props.builderState.state.calloutText || "Tip"}</h2> <p>{props.text}</p> </div> ); }; export default CustomTip;

What's next

Read more about binding data within the Data binding overview. To learn how to add more values to state directly from Builder, visit Content inputs.

Was this article helpful?