Best way to include custom CSS in a Story and its code block

[mnoble01]

Summary

I've been trying to figure out a good way to include custom CSS in a Story and it's code block so that

1. The rendered story includes the custom CSS
2. The code block on the docs page accurately represents the custom CSS, along with any updates to "controls"
3. The code block on the Story page accurately represents the custom CSS, along with any updates to "controls"

I found a few ways to do it, though I don't love any of them. I'd be curious to know how other people approach this and which option you like best.

Check out https://stackblitz.com/edit/custom-css-in-story-code?file=src%2Fstories%2FSimpleComponent.stories.tsx for a reproduction of everything I tried.

During this process, I found what I think is a bug where the code transform function is applied twice on docs pages. That's filed at http://github.com/storybookjs/storybook/issues/35889.

Additional information

Option (1)

/**
 * This outputs curly braces in the Story's code block
 */
export const CustomCSSWithRenderFn: Story = {
  args: {
    className: 'custom-class',
  },
  parameters: {
    customCss: dedent`
      .custom-class {
        width: 100px;
        height: 150px;
      }
    `,
  },
  render: (args, { parameters }) => (
    <>
      <style>{parameters.customCss}</style>
      <SimpleComponent {...args} />
    </>
  ),
};

Option (2)

/**
 * This demonstrates the double application of the transform function. The double
 * transform only occurs on the docs page example, not in the Story page's Code
 * panel.
 */
export const CustomCSSWithSourceTransform: Story = {
  args: {
    className: 'custom-class',
  },
  parameters: {
    customCss: dedent`
      .custom-class {
        width: 100px;
        height: 150px;
      }
    `,
    docs: {
      source: {
        // The <style> lives in a decorator, so it's excluded from the serialized
        // snippet. Prepend it so the example shows the CSS.
        transform: (
          code: string,
          { parameters }: { parameters: { customCss: string } }
        ) => {
          const styleBlock = `<style>\n${parameters.customCss}\n</style>`;
          return `${styleBlock}\n\n${code}`;
        },
      },
    },
  },
  decorators: [
    (Story, { parameters }) => (
      <>
        <style>{parameters.customCss}</style>
        <Story />
      </>
    ),
  ],
};

Option (3)

/**
 * This requires guarding against the double-transform invocation
 */
export const CustomCSSWithIdempotentSourceTransform: Story = {
  args: {
    className: 'custom-class',
  },
  parameters: {
    customCss: dedent`
      .custom-class {
        width: 100px;
        height: 150px;
      }
    `,
    docs: {
      source: {
        // The <style> lives in a decorator, so it's excluded from the serialized
        // snippet. Prepend it so the example shows the CSS. Storybook applies this
        // transform twice, so it must be idempotent to avoid duplicate <style> blocks.
        transform: (
          code: string,
          { parameters }: { parameters: { customCss: string } }
        ) => {
          const styleBlock = `<style>\n${parameters.customCss}\n</style>`;
          return code.includes(styleBlock) ? code : `${styleBlock}\n\n${code}`;
        },
      },
    },
  },
  decorators: [
    (Story, { parameters }) => (
      <>
        <style>{parameters.customCss}</style>
        <Story />
      </>
    ),
  ],
};

Option (4)

/**
 * This requires duplication of custom CSS and doesn't keep the source code
 * up to date with the current "controls" values
 */
export const CustomCSSWithDuplicatedStaticSource: Story = {
  args: { className: 'custom-class' },
  parameters: {
    customCss: dedent`
      .custom-class {
        width: 100px;
        height: 150px;
      }
    `,
    docs: {
      source: {
        // Keep in sync with `customCss` above.
        code: dedent`
          <style>
            .custom-class {
              width: 100px;
              height: 150px;
            }
          </style>

          <SimpleComponent className="custom-class" />
        `,
      },
    },
  },
  decorators: [
    (Story, { parameters }) => (
      <>
        <style>{parameters.customCss}</style>
        <Story />
      </>
    ),
  ],
};

Option (5)

const customClassCss = dedent`
  .custom-class {
    width: 100px;
    height: 150px;
  }
`;
/**
 * This requires a custom CSS variable that lives outside of the Story object and
 * doesn't keep the source code up to date with the current "controls" values
 */
export const CustomCSSWithModuleScopeVar: Story = {
  args: {
    className: 'custom-class',
  },
  decorators: [
    (Story) => (
      <>
        <style>{customClassCss}</style>
        <Story />
      </>
    ),
  ],
  parameters: {
    docs: {
      source: {
        code: dedent`
          <style>
            ${customClassCss}
          </style>

          <SimpleComponent className="custom-class" />
        `,
      },
    },
  },
};

Create a reproduction

https://stackblitz.com/edit/custom-css-in-story-code?file=src%2Fstories%2FSimpleComponent.stories.tsx

[MLuc24]

The reason every option feels wrong is that you're asking one mechanism to do two unrelated jobs. Rendering and snippet generation are separate pipelines in Storybook, so the clean version splits the problem instead of picking a compromise.

The relevant detail is in code/renderers/react/src/docs/jsxDecorator.tsx:

const storyJsx = context.originalStoryFn(context.args, context);

The snippet is serialized from originalStoryFn — the story as you wrote it, before decorators are applied. That single line explains both of your dead ends:

• Put the <style> in a decorator → it renders, and it is invisible in the code block, because decorators are not part of originalStoryFn.
• Put it in render → it is part of originalStoryFn, so it gets serialized, and {parameters.customCss} is serialized as the expression it literally is. Hence your curly braces in Option 1.

So use the decorator for rendering and docs.source.transform for display:

const meta: Meta<typeof SimpleComponent> = {
  component: SimpleComponent,
  decorators: [
    (Story, { parameters }) => (
      <>
        {parameters.customCss && <style>{parameters.customCss}</style>}
        <Story />
      </>
    ),
  ],
  parameters: {
    docs: {
      source: {
        transform: (code: string, ctx: any) => {
          const css = ctx.parameters?.customCss;
          if (!css) return code;
          const block = `<style>{\`\n${css}\n\`}</style>`;
          // Guard against the transform running more than once (#35889)
          if (code.includes(block)) return code;
          return `${block}\n${code}`;
        },
      },
    },
  },
};

export const CustomCSS: Story = {
  args: { className: 'custom-class' },
  parameters: {
    customCss: dedent`
      .custom-class { width: 100px; height: 150px; }
    `,
  },
};

This gives you all three of your requirements. The story renders with the CSS because the decorator applies it. Both code blocks show the CSS because transform prepends it. And control changes stay accurate because transform receives the freshly generated code for the current args — it's post-processing a live snippet, not replacing it with a frozen string.

That last point is why I'd avoid docs.source.code here even though it's the most direct way to control the output: it's static, so it wins on the CSS and loses requirement 2 and 3 the moment someone touches a control.

The includes(block) guard is what makes this survive the double-application you filed in #35889. Writing the transform to be idempotent is worth doing regardless of that bug — it costs one line and means the snippet is correct whether the transform runs once or twice.

One thing to check on your side: if you ever set parameters.docs.source.type, note that skipJsxRender in the same file keys off it, and SourceType.DYNAMIC forces the dynamic path. Leaving it unset is what you want for this setup.