Create a story

In this how-to, you'll learn how stories work in React Bricks and how to create them in the 2 supported ways:

• from the editor
• in code, inside a brick's schema

Docs reference: Stories

What a story is

A story is a named set of props for a brick.

When you apply a story, React Bricks creates a brick using those saved props.

This is useful when you want a "cookie cutter" for a brick configuration.

For example, you may want:

• a few approved hero variants
• a pre-styled call to action
• a testimonial with a known layout and visual style

Unlike an embed, a story is not a live connection to a shared source.

Once the story is applied, the brick can be edited independently.

So if you later change the original story, the bricks that already used it do not update automatically.

When stories are a good fit

Stories are a good fit when:

• you want to reuse a brick configuration many times
• editors should be free to tweak each instance after inserting it
• you want to offer design-system variants directly in the editor

If instead you need "change once, apply everywhere", use an embed. We'll cover that in the next guide: Reuse a fragment (embed)

Create a story from the editor

Editors can save a story from the Content Editor starting from an existing brick.

The flow is simple:

1. Select a brick.
2. Configure th brick the way you want.
3. Open the Stories tab in the editor sidebar.
4. Save the current brick configuration as a named story.

That story is stored by React Bricks and can then be reused by editors in other pages.

This is a great option when:

• content editors discover a useful variation while editing
• the reusable pattern is content-driven rather than hard-coded in the design system
• developers do not need to ship code for every reusable preset

Define stories in code

If a story is part of your design system, define it directly in the brick's schema using the stories array.

import { types } from 'react-bricks/rsc'
 
interface HeroUnitProps {
  title: string
  subtitle: string
  dark: boolean
}
 
const HeroUnit: types.Brick<HeroUnitProps> = () => {
  return null
}
 
HeroUnit.schema = {
  name: 'hero-unit',
  label: 'Hero Unit',
  stories: [
    {
      id: 'black-friday-cta',
      name: 'CTA for Black Friday',
      showAsBrick: true,
      previewImageUrl: '/images/bricks/hero-black-friday.png',
      props: {
        title: 'Black Friday discount',
        subtitle: 'Save 30% this week only',
        dark: true,
      },
    },
    {
      id: 'simple-light-hero',
      name: 'Simple light hero',
      props: {
        title: 'Welcome to our site',
        subtitle: 'A clean hero for marketing pages',
        dark: false,
      },
    },
  ],
}
 
export default HeroUnit

In this example:

• each story has an id
• name is what editors see in the UI
• props contains the values applied to the brick
• showAsBrick: true makes the story appear directly in the add-brick interface
• previewImageUrl is useful when showAsBrick is enabled

What showAsBrick is for

Normally, a story is applied to an existing brick.

When you set:

showAsBrick: true

the story behaves more like a ready-made brick variant in the add-brick menu.

This is useful when you want editors to think in terms of:

• "Add the dark CTA hero"
• "Add the testimonial quote version"
• "Add the compact feature card"

instead of first inserting a generic brick and then choosing a story.

Use stories in default content

Stories are also useful in getDefaultContent for page types or template slots.

For example:

getDefaultContent: () => [
  {
    brickName: 'hero-unit',
    storyName: 'black-friday-cta',
  },
]

This creates the new page with a brick already initialized from that story.

Editor-created stories vs code-defined stories

Both approaches are useful, but they solve slightly different needs.

Use editor-created stories when:

• the variation is content-driven
• editors should save their own favorite presets
• you do not want to deploy code for each new variation

Use code-defined stories when:

• the variation belongs to the design system
• you want stable, curated presets in every environment
• you want to expose a story as a dedicated brick option with showAsBrick

Summary

Stories help you reuse a brick's configuration, not its live content.

That makes them perfect for reusable presets and design-system variants.

If you need a live shared fragment instead, use an embed: Reuse a fragment (embed)