This guide assumes you are working within the Code Editor. If you are working locally, be sure to commit and push changes to your preview branch for them to take effect in Stackbit.

Let's walk through the process of adding a new component to a Stackbit site, which can then be added to the site's pages.

For this example, we'll create an AlertSection component. It will have a single text property, which will be styled and rendered as centered, white text on a primary background.

How the AlertSection component is rendered

We are calling this AlertSection and not just Alert to make it more obvious that we are creating a section component. Section components are those that are added directly to pages.

Create Alert Component

Begin by creating a basic alert component that renders the text prop. Create a file at src/components/sections/AlertSection.tsx for this component.

// src/components/sections/AlertSection.tsx
import React from 'react'

const AlertSection = ({ text }) => {
  return (
    <div className="py-6 bg-primary">
      <div className="container mx-auto">
        <p className="text-center text-xl text-white">{text}</p>
      </div>
    </div>
  )
}

export default AlertSection

Stackbit sites are styled using Tailwind by default. Any class supported by Tailwind can be used in components.

Register the Component

Next, register the component in src/components/components-registry.ts. This tells Stackbit where to find the AlertSection component.

// src/components/components-registry.ts

const components = {
  AlertSection: dynamic(() => import('./sections/AlertSection'))
  // ...
}

Add Component Model

We have a component and Stackbit knows about the component. But we haven't told Stackbit about the data structure of the component. To do that, let's add a data model for our AlertSection component at .stackbit/models/AlertSection.yaml.

# .stackbit/models/AlertSection.yaml

name: AlertSection
label: Alert Section
groups:
  - sectionComponent
fields:
  - type: text
    name: text

You have a lot of options when it comes to adding fields to models in Stackbit. Here's the reference.

Add Component to the Page

Now you can go to the page editor and add an AlertSection component to your page.

Editing AlertSection section on page editor

Note that Stackbit automatically applies a default value to the text.

Enabling Highlights

That's exciting, but we still can't highlight our component from the page editor. We can enable visual editing using Annotations.

In this particular case, we're making use of data-sb-field-path to tell Stackbit how to map the text content to the element containing the text text on the page.

// src/components/sections/AlertSection.tsx
import React from 'react'
import { getDataAttrs } from '../../utils/get-data-attrs'

const AlertSection = ({ text, ...props }) => {
  return (
    <div {...getDataAttrs(props)} className="py-6 bg-primary">
      <div className="container mx-auto">
        <p data-sb-field-path=".text" className="text-center text-xl text-white">
          {text}
        </p>
      </div>
    </div>
  )
}

export default AlertSection

getDataAttrs is a utility that renders any data attributes specified on the parent. This helps with annotations.

Go back to the page editor and voila! You can now highlight the AlertSection content.

Enabling highlights on AlertSection component

Note that when you are in the code editor and have highlighted the components, you get the option to jump directly to the code. This is only available if your component imports React, as shown in the examples above.

Next Steps

There is a lot more you can do with custom components. This was just a simple example to get you started. Here are some recommended next steps:

  • Define Content Presets. These are the content permutations (and accompanying thumbnails) that will provide your component will some default content.
  • Add User-Controlled Styles. Surface options to content editors to enable them to adjust style properties like font size, background color, and more.
  • Add more fields. Build up the model, make your component do what you need it to do!