Builder.io React SDK
Integration
See our full getting started docs, or jump right into integration. We generally recommend to start with page buliding as your initial integration:
Integrate Page Building | Integrate Section Building |
|
|
React API
Simple example
The gist of using Builder, is fetching content (using queries on custom fields and targeting. Builder is structured like a traditional headless CMS where you can have different content types, called models. By default, every Builder space has a "page"
model.
import { builder } from '@builder.io/react'
const API_KEY = '...'
const MODEL_NAME = 'page';
const content = await builder
.get(MODEL_NAME, {
query: {
'data.customField.$gt': 100,
},
userAttributes: {
urlPath: '/'
}
})
.promise()
<BuilderComponent model={MODEL_NAME} content={content} />
The builder content is simply json that you pass to a <BuilderComponent />
to render. Learn more about it here
You can view all of the options for builder.get
for fetching content in our full reference here
For example, with Next.js, to render Builder as your homepage:
export const getStaticProps = async () => {
return {
props: {
builderContent: await builder.get('page', {
userAttributes: {
urlPath: '/'
}
}).promise()
}
}
}
export default function MyHomePage({ builderContent }) {
return <>
<YourHeader />
<BuilderComponent model="page" content={builderContent} />
<YourFooter />
</>
}
You can also allow dynamic page building (the ability to create new pages on new URLs dynamically). E.g. see this guide on how to do that
Registering Components
One of Builder's most powerful features is registering your own components for use in the drag and drop editor.
You can choose to have these compliment the built-in components, or to be the only components allowed to be used
(e.g. via components-only mode)
import { Builder } from '@builder.io/sdk-react';
function MyHero(props) { }
Builder.registerComponent(MyHero, {
name: 'Hero',
inputs: [
{ name: 'title', type: 'string' }
]
})
Learn more about registering components in Builder
BuilderComponent
You can find the full reference docs for the BuilderComponent props here
const MODEL_NAME = 'page';
<BuilderComponent model={MODEL_NAME} content={builderJson} />
See our guides for Gatsby and Next.js for guides on using with those frameworks
Passing data and functions down
You can also pass data and functions down to the Builder component to use in the UIs (e.g. bind
data values to UIs e.g. for text values or iterating over lists, and actions to trigger for instance on click of a button)
All data passed down is available in Builder actions and bindings as state.*
, for instance in the below example state.products
, etc will be available
<BuilderComponent
model="page"
data={{
products: productsList,
foo: 'bar'
}}
content={builderJson} />
You can also pass down functions, complex data like custom objects and libraries you can use context
. Similar to React context, context passes all the way down (e.g. through symbols, etc). This data is not observed for changes and mutations
<BuilderComponent
model="page"
context={{
addToCart: () => myService.addToCart(currentProduct),
lodash: lodash,
}}
content={builderJson} />
Context is available in actions and bindings as context.*
, such as context.lodash
or context.myFunction()
in the example above
Passing complex data
Everything passed down is available on the state
object in data and actions - e.g. state.products[0].name
See more about using data passed down here
Builder
The global Builder
singleton has a number of uses. Most important is registering custom components.
import * as React from 'react';
import SyntaxHighlighter from 'react-syntax-highlighter';
import { Builder } from '@builder.io/react';
class CodeBlockComponent extends React.Component {
render() {
return <SyntaxHighlighter language={this.props.language}>{this.props.code}</SyntaxHighlighter>;
}
}
Builder.registerComponent(CodeBlockComponent, {
name: 'Code Block',
inputs: [
{
name: 'code',
type: 'string',
defaultValue: 'const incr = num => num + 1',
},
{
name: 'language',
type: 'string',
defaultValue: 'javascript',
},
],
});
See our full guide on registering custom components here.
See the full reference docs for registerComponent options here.
BuilderContent
Usage with Data Models
Although you can already fetch data models from our Content API directly and use it as you would any other API resource, with a BuilderContent component you are able to use live Editing / Previewing / A/B testing of your Data Models within the Builder Visual Editor.
Example, setting up an editable theme:
<BuilderContent model="site-settings"> { (data, loading) => {
If (loading) {
return <Spinner />
}
return <>
/*pass values down to an example ThemeProvider, used as a wrapper in your application*/
<ThemeProvider theme={data.theme} >
{props.children}
</ThemeProvider>
</>
}}
</BuilderContent>
Or an example fetching server side and passing the content using the content
prop, e.g. in Next.js
export const getStaticProps = async () => {
return {
props: {
builderDataContent: await builder.get('site-settings', ).promise()
}
}
}
export default function MyPage({ builderDataContent }) {
return <BuilderContent content={builderDataContent}>{data =>
<ThemeProvider theme={data.theme}>
{/* ... more content ... */}
</ThemeProvider>
</BuilderContent>
}
Usage with Page/Section Custom Fields
Page and section models in builder can be extended with custom fields. To enable live editing / previewing on components that uses those custom fields, you can use BuilderContent to pass input data from the model to your components that are outside the rendered content
Example, passing Custom Field input:
<BuilderContent model="landing-page">{ (data) => {
return <>
<FeaturedImage image={data.featuredImage} />
<BuilderComponent content={content} model="landing-page" />
</>
}}
</BuilderContent>
Passing content manually
This is useful for doing server side rendering, e.g. with Gatsby and Next.js or via
loading data from other sources than our default APIs, such as data in your own database saved via webhooks
const content = await builder.get(‘your-data-model’, { ...options });
if (content) {
return <BuilderContent model="your-data-model" content={content} >
}
Advanced querying
When using custom models and fields you can do more advanced filtering of your content with queries
and targeting
import { BuilderContent, builder } from '@builder.io/react';
builder.setUserAttributes({ isLoggedIn: false })
export default () => <div>
<BuilderContent
model="your-data-model"
options={{ query: { 'data.something.$in': ['value a', 'value b'] } }} />
</div>
builder
The React SDK exports the core SDK's builder object, which can be used for setting things like
your API key and user attributes
import { builder } from '@builder.io/react';
builder.init(YOUR_KEY);
builder.setUserAttributes({
userIsLoggedIn: true,
whateverKey: 'whatever value',
});