Stories

Stories, along with Embed, offer a way to re-use content across pages.

While embedding a page within another provides a “single source of truth” (changes to an embedded page affect all pages embedding it), a “story” acts more like a template for bricks.

A story is a named set of props for a brick. When you apply a story to a brick, you’re applying these saved props. After application, the brick can be modified independently, without maintaining any connection to its original story.

How to create a story

Stories can be created in two ways:

From the editor: Using the “Stories” tab when a block is selected. These stories are saved to the React Bricks database and retrieved via APIs by the editor interface.
In code: By the developer, using the stories array in the brick’s schema. These stories reside in your design system’s code.

Stories saved from the Editor interface

Here’s’ how content editors can save stories for a brick from the editor interface:

Stories set in code

In the brick’s schema, you can define an array of stories using the stories property. You can also specify whether a story appears as a normal brick in the “Add new brick” menu by setting the story’s showAsBrick flag to true.

Example usage

HeroUnit.schema = {
  ...
  stories: [
    {
      id: 'black-friday-cta',
      name: 'CTA for Black Friday',
      props: {
        title: 'Black friday discount',
        background: { color: '#000', className: 'bg-black' }
      },
      showAsBrick: true
    },
  ],
}

Properties

Each element has the following TypeScript interface (the generic type is inherited from the brick’s component interface):

type BrickStory<T = Props> = {
  id: string
  name: string
  showAsBrick?: boolean
  previewImageUrl?: string
  props: T
}

Properties definition

Property	Definition
`id`	Unique identifier for this story.
`name`	Name for the story displayed in the editor.
`showAsBrick`	If `true`, the story appears as a new brick in the “Add new brick” interface, making it directly selectable. Default: `false`.
`previewImageUrl`	Preview image for this story (required only if `showAsBrick` is true).
`props`	The object containing the props to be applied by this story.