New guide: AI is in production. Is your governance?

Announcing Visual Copilot - Figma to production in half the time

Builder.io
Builder.io
Contact sales

New guide: AI is in production. Is your governance?

Announcing Visual Copilot - Figma to production in half the time

enterprise plans

You can use Builder Sections to create reusable content across multiple pages. You can manage the code within your codebase, and teammates in the UI can iterate in the Visual Editor.

Examples include:

This tutorial shows you how to create and add an announcement bar section to a page.

For more conceptual information Section Models, refer to the Section Models documentation.

To follow along with this tutorial, you should have the following:

  • a Builder account
  • an app in the framework of your choice with the appropriate Builder SDK installed

Create a page with the following contents. Make sure to replace YOUR_API_KEY with your Public API Key:

// pages/[...page].tsx
import React from "react";
import { useRouter } from "next/router";
import { BuilderComponent, builder, useIsPreviewing } from "@builder.io/react";
import { BuilderContent } from "@builder.io/sdk";
import { GetStaticProps } from "next";

// Replace with your Public API Key
builder.init(YOUR_API_KEY);

// Define a function that fetches the Builder
// content for a given page
export const getStaticProps: GetStaticProps = async ({ params }) => {
  // Fetch the builder content for the given model
  const announcementBar = await builder
    .get("announcement-bar", {
      userAttributes: {
        urlPath: "/" + ((params?.page as string[])?.join("/") || ""),
      },
    })
    .toPromise();

  // Return the announcement bar content as props
  return {
    props: {
      announcementBar: announcementBar || null,
    },
    // Revalidate the content every 5 seconds
    revalidate: 5,
  };
};

// Define the announcement bar component
export default function announcementBar({ announcementBar }: { page: BuilderContent | null }) {
  const router = useRouter();
  const isPreviewing = useIsPreviewing();

  // If the announcement bar is available, render
  // the BuilderComponent with the content

  return (
    <>
      {/* Render the announcement bar */}
      <BuilderComponent model="announcement-bar" content={announcementBar || undefined} />
    </>
  );
}

The BuilderComponent accepts several props for customization. One important prop for client-side routing is renderLink, which means you can implement custom routing. For more information on renderLink and other props, visit the renderLink entry in Using BuilderComponent.

Here's an example of how you might use the renderLink prop:

<BuilderComponent 
  model="page" 
  content={content} 
  renderLink={(props) => <CustomLink {...props} />}
/>

Sections are typically targeted using some information about the user's state.

For instance, you can display an announcement bar when the user visits particular URLs. With custom targeting attributes, you can even display content based on complex conditions, such as when a user adds a particular item to their cart.

Aside from targeting, you can also query sections by custom fields.

const urlPath = '/' + (params?.page?.join('/') || '');

const announce = await builder
    .get('announcement-bar', { userAttributes: { urlPath } })
    .toPromise();

The announcement bar section in the example above is targeted with the current URL using the urlPath targeting attribute. When Builder finds an announcement bar with a matching URL, it responds with that announcement bar's content.

The snippet below demonstrates how the announcement bar is rendered in the context of the page.

return (
  <>
    <!-- Put your header here -->
    <YourHeader />
    <BuilderComponent model="announcement-bar" content={announce} />
    <!-- The rest of your page -->
    <TheRestOfYourPage />`
  </>
);

BuilderComponent receives the content for the announcement bar through the content prop and renders it next to your page's content.

You can also render a Builder-managed page next to your announcement bar or any other section by placing multiple BuilderComponent instances next to each other.

Check out How to Create a Page for a step-by-step tutorial on how to create a page in Builder and Integrating Pages on how to render your page content within your template.

Create a Section model so you can make an announcement bar content entry.

  1. Go to Models.
  2. Click +Create Model.
  3. Select Section.
  4. Enter Announcement bar as the name for your new Section model.
  5. For all frameworks except Swift: change the Preview URL on the Model Options page to the URL of the page that you added code to display your section. This example uses http://localhost:####/announcements, but yours might be different.
  6. Click Save.

The video below demonstrates this process:

When you create or edit an announcement bar section, the Visual Editor displays your content embedded within your Preview URL page, providing visual context and importing styles from your site. It's a live view of your section, as it will look on one of your pages when you publish.

Published Sections typically appear across multiple pages with different URLs depending on how they're targeted. When previewing in the editor, however, they only appear within the Preview URL's page. For more information, refer to Editing and Previewing Your Site.

For more information what Section Models are and how to use them, refer to the Section Models documentation.

Now that your Section model is set up, you can create an announcement bar content entry to add an announcement bar to your site.

  1. Go to Content.
  2. Click the + New Entry button and select Announcement bar.
  3. Build and style your announcement bar.
  4. Name the content entry.
  5. Click Publish.

The video below demonstrates this process:

To make your announcement bar display based on targeting, in the section content entry; for example, in the announcement bar:

  1. Click on the Targeting icon.
  2. For Where, select URL path.
  3. Add the URL path you'd like to target.
  4. Click the Publish button.

The video below shows this process in an integrated Remix app where the targeted URL path is /builder so that the announcement bar doesn't show up on any other URLs. This process is the same, regardless of the framework you use. The URL path you target, however, might differ.

If you're using Gatsby, you might need to restart your app to render the announcement bar.

When working with sections that use custom fields or data models, it's helpful to set up live previewing. In this way you get real-time updates in the Visual Editor without having to publish your changes.

For detailed instructions on setting up live previewing for your custom fields and data models, visit Live Previewing Data Models and Custom Fields.

With your app and Builder working together, the next step is the fun part–add some more Sections in Builder and drag in some elements. Play with styles and explore the UI.

Deploy your updated app to a preview environment

Integrate Custom Components

Was this article helpful?