Symbols are a type of Section model you can integrate for editing on your site or app. They help you elegantly reuse content across many Builder Pages and Sections. For more information, see Intro to Symbols.
To get the most out of this document, you should have:
Create a special page on your site specifically for Symbol editing. This is what the Builder preview opens when you create and edit symbols. It's important this be on a URL directly on your site, so all previewing and editing are accurate.
In this example, this page is named /edit-symbol.
Create a page with the following contents. Make sure to replace YOUR_API_KEY with your Public API Key:
// pages/edit-symbol.jsx
import { BuilderComponent, builder } from '@builder.io/react';
// Replace with your Public API Key.
builder.init(YOUR_API_KEY);
export default function Page() {
return <BuilderComponent model="symbol" />
}BuilderComponent gives the drag and drop Visual Editor a region to work in in your site.
Note that if you have registered custom components, you must import them on this page so that they are available in the Visual Editor.
Create a page with the following contents. Make sure to replace YOUR_API_KEY with your Public API Key:
import type { GetServerSideProps } from 'next'
import { fetchOneEntry, Content } from '@builder.io/sdk-react'
import type { BuilderContent } from '@builder.io/sdk-react'
const API_KEY = 'YOUR_API_KEY'
export const getServerSideProps: GetServerSideProps<{
symbol: BuilderContent | null
}> = async () => {
const symbol = await fetchOneEntry({
model: 'symbol',
apiKey: API_KEY,
userAttributes: { urlPath: '/symbol-hero' },
})
return { props: { symbol: symbol || null } }
}
export default function SymbolHeroPage({
symbol,
}: {
symbol: BuilderContent | null
}) {
return symbol ? (
<Content model="symbol" apiKey={API_KEY} content={symbol} />
) : (
<div>Loading or 404</div>
)
}Content allows the drag and drop editor to work in the specified region of your site.
Note that if you have registered custom components, you must import them on this page so that they are available in the Visual Editor.
Create a page with the following contents. Make sure to replace YOUR_API_KEY with your Public API Key:
// app/edit-symbol/page.tsx
import { BuilderComponent, builder } from '@builder.io/react';
// Replace with your Public API Key.
const BUILDER_API_KEY = 'YOUR_API_KEY';
builder.init(BUILDER_API_KEY);
const EditSymbolPage = () => {
return <BuilderComponent model="symbol" />
};
export default EditSymbolPage;
BuilderComponent allows the drag and drop editor to work in the specified region of your site.
Note that if you have registered custom components, you must import them on this page so that they are available in the Visual Editor.
Create a page with the following contents. Make sure to replace YOUR_API_KEY with your Public API Key:
import { fetchOneEntry, Content } from '@builder.io/sdk-react'
const API_KEY = /* YOUR PUBLIC API KEY */
export default async function SymbolHeroPage() {
const symbol = await fetchOneEntry({
model: 'symbol',
apiKey: API_KEY,
userAttributes: { urlPath: /* YOUR SYMBOL PATH */ },
})
return symbol ? (
<Content model="symbol" apiKey={API_KEY} content={symbol} />
) : (
<div>404</div>
)
}Content allows the drag and drop editor to work in the specified region of your site.
Note that if you have registered custom components, you must import them on this page so that they are available in the Visual Editor.
Create a page with the following contents. Make sure to replace YOUR_API_KEY with your Public API Key:
// src/EditSymbol.jsx
import { BuilderComponent, builder } from '@builder.io/react';
// Replace with your Public API Key.
const BUILDER_API_KEY = 'YOUR_API_KEY';
// Initialize Builder.io with your API key.
builder.init(BUILDER_API_KEY);
const EditSymbol = () => {
{/* This allows the Builder.io Visual Editor to work with the symbol model */}
return <BuilderComponent model="symbol" />
};
export default EditSymbol;
BuilderComponent allows the drag and drop editor to work in the specified region of your site.
Note that if you have registered custom components, you must import them on this page so that they are available in the Visual Editor.
Create a page with the following contents. Make sure to replace YOUR_API_KEY with your Public API Key:
// src/EditSymbol.jsx
import { BuilderContent, Content, fetchOneEntry } from "@builder.io/sdk-react";
import { useEffect, useState } from "react";
const BUILDER_API_KEY = /* YOUR PUBLIC API KEY HERE */;
const EditSymbol = () => {
const [content, setContent] = useState<BuilderContent | null>(null);
useEffect(() => {
fetchOneEntry({
model: "symbol", // The Builder model to fetch from
apiKey: BUILDER_API_KEY,
userAttributes: {
urlPath: /* SYMBOL's PATH */,
}}).then((content) => {
setContent(content);
});
}, []);
// Render the Builder.io content using the Content component
return content ? (
<Content model="symbol" apiKey={BUILDER_API_KEY} content={content} />
) : (
<div>404</div>
);
};
export default EditSymbol;
Content allows the drag and drop editor to work in the specified region of your site.
Note that if you have registered custom components, you must import them on this page to be available in the Visual Editor.
Paste the following code into a new file within the routes directory called $.tsx, making sure to replace YOUR_API_KEY with your Public API Key.
import type { LoaderArgs } from '@remix-run/node'
import { json, useLoaderData } from '@remix-run/react'
import { fetchOneEntry, Content } from '@builder.io/sdk-react'
import type { BuilderContent } from '@builder.io/sdk-react'
const BUILDER_API_KEY = 'ADD_YOUR_PUBLIC_API_KEY';
export async function loader({ request }: LoaderArgs) {
const symbol = await fetchOneEntry({
model: 'symbol',
apiKey: BUILDER_API_KEY,
userAttributes: { urlPath: 'YOUR_SYMBOL_PATH' },
})
return json<{ symbol: BuilderContent | null }>({ symbol })
}
export default function SymbolPage() {
const { symbol } = useLoaderData<typeof loader>()
return symbol ? (
<Content model="symbol" apiKey={BUILDER_API_KEY} content={symbol} />
) : (
<div>Loading or 404</div>
)
}
The BuilderComponent provides a place for the Builder content model named symbol to render.
import { fetchOneEntry, Content } from '@builder.io/sdk-react'
const API_KEY = 'YOUR_API_KEY'
export default async function SymbolHero() {
const symbol = await fetchOneEntry({
model: 'symbol',
apiKey: API_KEY,
userAttributes: { urlPath: '/symbol-hero' },
})
if (!symbol) return <div>Loading or 404</div>
return <Content model="symbol" apiKey={API_KEY} content={symbol} />
}
Add the following to routes/edit-symbol/+page.svelte:
<script lang="ts">
import type { BuilderContent } from '@builder.io/sdk-svelte';
import Content from '@builder.io/sdk-svelte';
export let data: { content: BuilderContent | null };
const API_KEY = /* ADD YOUR PUBLIC API KEY HERE */;
const MODEL = 'symbol';
</script>
{#if !data.content}
<div>Loading or Not Found</div>
{:else}
<Content model={MODEL} apiKey={API_KEY} content={data.content} />
{/if}
Add the following to src/routes/edit-symbol/+page.ts:
import { fetchOneEntry, type BuilderContent } from '@builder.io/sdk-svelte';
import type { PageLoad } from './$types';
const API_KEY = /* ADD YOUR PUBLIC API KEY */;
const MODEL = 'symbol';
export const load: PageLoad = async () => {
const content: BuilderContent | null = await fetchOneEntry({
model: MODEL,
apiKey: API_KEY,
userAttributes: { urlPath: /* ADD YOUR SYMBOL PATH */ },
});
return { content };
};Make sure to replace YOUR_API_KEY with your Public API Key.
<script lang="ts">
import { onMount } from 'svelte';
import { fetchOneEntry, Content } from '@builder.io/sdk-svelte';
import type { BuilderContent } from '@builder.io/sdk-svelte';
const API_KEY = YOUR_PUBLIC_API_KEY_HERE';
const MODEL = 'symbol';
let content: BuilderContent | null = null;
onMount(async () => {
content = await fetchOneEntry({
model: MODEL,
apiKey: API_KEY,
userAttributes: { urlPath: '/symbol-hero' },
// options: { query: { name: 'Hero Video' } }, // optional
});
console.log('symbol content', content);
});
</script>
{#if !content}
<div>Loading…</div>
{:else}
<Content {MODEL} apiKey={API_KEY} content={content} />
{/if}
<template>
<div>
<div v-if="!symbol">Loading...</div>
<Content
v-else
:model="model"
:apiKey="apiKey"
:content="symbol"
/>
</div>
</template>
<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { Content, fetchOneEntry } from '@builder.io/sdk-vue'
import type { BuilderContent } from '@builder.io/sdk-vue'
const apiKey = 'YOUR_API_KEY'
const model = 'symbol'
const symbol = ref<BuilderContent | null>(null)
onMounted(async () => {
symbol.value = await fetchOneEntry({
model,
apiKey,
userAttributes: { urlPath: '/YOUR_SYMBOL_PATH' },
})
})
</script>
Create a file called pages/edit-symbol.vue with the following contents. Make sure to replace YOUR_API_KEY with your Public API Key:
<script setup lang="ts">
import { useAsyncData } from '#app'
import { Content, fetchOneEntry } from '@builder.io/sdk-vue'
import type { BuilderContent } from '@builder.io/sdk-vue'
const apiKey = 'YOUR_API_KEY'
const model = 'symbol'
const { data: symbol } = await useAsyncData<BuilderContent | null>(
'symbolHero',
() =>
fetchOneEntry({
model,
apiKey,
userAttributes: { urlPath: '/SYMBOL_PATH' },
})
)
</script>
<template>
<div>
<div v-if="!props.symbol">Loading...</div>
<Content
v-else
:model="props.model"
:apiKey="props.apiKey"
:content="props.symbol"
/>
</div>
</template>
Content allows the drag and drop editor to work in the specified region of your site.
import { Component } from '@angular/core'
import { fetchOneEntry, type BuilderContent, Content } from '@builder.io/sdk-angular'
@Component({
selector: 'app-symbol-hero',
standalone: true,
imports: [Content],
template: `
<div *ngIf="!symbol">Loading...</div>
<builder-content
*ngIf="symbol"
[model]="model"
[content]="symbol"
[apiKey]="apiKey"
></builder-content>
`
})
export class SymbolHeroComponent {
apiKey = 'YOUR_API_KEY'
model = 'symbol'
symbol: BuilderContent | null = null
async ngOnInit() {
this.symbol = await fetchOneEntry({
model: this.model,
apiKey: this.apiKey,
userAttributes: { urlPath: /* YOUR SYMBOL PATH */ },
})
}
}
import { Component } from '@angular/core'
import { fetchOneEntry, type BuilderContent, Content } from '@builder.io/sdk-angular'
@Component({
selector: 'app-symbol-hero',
standalone: true,
imports: [Content],
template: `
<div *ngIf="!symbol">Loading...</div>
<builder-content
*ngIf="symbol"
[model]="model"
[content]="symbol"
[apiKey]="apiKey"
></builder-content>
`
})
export class SymbolHeroComponent {
apiKey = 'YOUR_API_KEY'
model = 'symbol'
symbol: BuilderContent | null = null
async ngOnInit() {
this.symbol = await fetchOneEntry({
model: this.model,
apiKey: this.apiKey,
userAttributes: { urlPath: /* YOUR SYMBOL PATH */ },
})
}
}
Create a page with the following contents:
// src/pages/edit-symbol.jsx
import * as React from 'react';
import { BuilderComponent } from '@builder.io/react';
function SymbolEditingPage() {
return (
<BuilderComponent model="symbol" />
);
}
export default SymbolEditingPage;BuilderComponent allows the drag and drop editor to work in the specified region of your site.
Note that if you have registered custom components, you will need to import them on this page so that they are available in the Visual Editor.
import React, { useEffect, useState } from 'react'
import { Content, fetchOneEntry } from '@builder.io/sdk-react'
const API_KEY = 'YOUR_API_KEY'
export default function SymbolHero() {
const [symbol, setSymbol] = useState(null)
useEffect(() => {
fetchOneEntry({
model: 'symbol',
apiKey: API_KEY,
userAttributes: { urlPath: '/symbol-hero' },
}).then(setSymbol)
}, [])
return symbol ? (
<Content model="symbol" apiKey={API_KEY} content={symbol} />
) : (
<div>Loading...</div>
)
}Fetch your announcement bar's pre-rendered HTML from Builder's HTML API. Then inject it into your app's page template.
The example below uses Express.js.
// your-app.js
app.get("/edit-symbol", async (req, res) => {
const apiKey = YOUR_API_KEY;
const encodedUrl = encodeURIComponent(req.url);
// You can also query, sort, and target this content.
// See full docs on our content API: https://www.builder.io/c/docs/query-api
const { data } = await fetch(
`https://cdn.builder.io/api/v1/html/announcement-bar?apiKey=${apiKey}&url=${encodedUrl}`
).then((res) => res.json());
res.send(`
<html>
<head>
<!-- Your normal head contents -->
</head>
<body>
${data.html}
</body>
</html>
`);
});
Make sure to replace YOUR_API_KEY with your Public API Key.
Add a new component for this demo using the Angular CLI tool, which will load the announcement bar section in your app:
ng generate component edit_symbolReplace the placeholder content in your component's template with the following:
// src/app/edit-symbol/edit-symbol.component.html
<builder-component model="symbol"></builder-component>Now, be sure to connect this component to your router so that it renders for /edit-symbol
For instructions on getting your Public API Key, see Finding Your Public API Key in Using Builder API Keys.
- Go to Models and choose the Symbol model. If you don't have Symbol here, make sure that you've met the prerequisite of having created a Symbol. For step-by-step instructions, read Making a Symbol.
- Enter your site domain at a specifc path, such as
/edit-symbol, for examplehttps://my-site.com/edit-symbol. - Click Save.
You can use localhost when testing locally, then change to a hosted URL like your QA or production URL once your code updates have been deployed.
For more examples of what you can do with Builder, check out the Blueprints, which cover varied use cases at a high-level with code examples.
