How to show controls for a story in docs

[scurk1415]

Summary

I am developing a component library with multiple types of components. I created stories for those components and the docs are displayed for them. What i want to achieve now is that every story also has the controls (that affect the story) displayed under it where the user can change the controls. Currently the controls get displayed only on the top of the docs page (all in the same table), but i also want to display them for every story separately.

Example:
My Badge component has an input/prop/args named size. I created a story/doc for it (picture 1). What I want to do now is add the control (picture 2), so that the user reading the docs can change the sizes right there at the story (not on top of the page with all the controls).

How it looks by default

What I want to add to the docs of the story

Is this possible to do?

Additional information

No response

Create a reproduction

No response

[smlimasu]

If your setup is that you write your Docs with mdx manually, you would need to have a Canvas-Block and a Controls-Block for every story. Writing MDX. Jump directly to the Autodocs explanation further down if you don't write docs pages in mdx.

Example MDX:

{/* Checkbox.mdx */}
 
import { Canvas, Controls, Subheading } from '@storybook/blocks';
 
import * as CheckboxStories from './Checkbox.stories';

<Subheading>Unchecked</Subheading>
<Canvas of={CheckboxStories.Unchecked} />
<Controls of={CheckboxStories.Unchecked} />

<Subheading>Unchecked</Subheading>
<Canvas of={CheckboxStories.Checked} />
<Controls of={CheckboxStories.Checked} include={['label']}  exclude={['background']} />

//and so on ... 

If I understand you correctly, you want only show the args you've set for that specific story, not all possible components args (like the default controls-block does it). Then you can set these strings in the exclude or include property of the controls block in the mdx, see above.

Sometimes, its better to organize this directly at the meta or story level, just set there

parameters{
   docs: {
      controls: {
           include: ['label'],
          },
      },
},

But, instead of writing all that stuff manually, you can create a react component that handles all that logic. Works in Storybook-Angular, too.

While you could use that component in mdx directly, the easiest is to define a docs-page-template for your use case. You can customize the DocsPage, see Documentation.

You can set this template at the preview(project), meta or story level for parameters.docs.page: myPageTemplate ... i also had shown another example of some customized autodocs in #29156 for more explanation.

Here is some example to insert to handle all that logic programmatically (show heading, story-description, canvas, and a controls block which only includes the args explicitly defined at the meta or the specific story level):

import {
  Subheading,
  Meta,
  DocsContext,
  Controls,
  Title,
  Source,
  Markdown,
  Canvas,
  Description,
  Heading,
} from '@storybook/blocks';
import React, { useContext } from 'react';

export const AutoDocsControls: React.FC = () => {
  const { componentStories, projectAnnotations, getStoryContext } =
    useContext(DocsContext);

  // Get all csf file stories
  let stories = componentStories();

  // base filter all csf file stories
  const { stories: { filter } = { filter: undefined } } =
    projectAnnotations.parameters?.['docs'] || {};
  if (filter) {
    stories = stories.filter((story) => filter(story, getStoryContext(story)));
  }

  // Filter to only include stories with 'autodocs' tags
  stories = stories.filter(
    (story) => story.tags?.includes('autodocs') && !story.usesMount
  );

  return (
    <>
      <Meta />
      <Title />
      <Description />
      <Heading>Stories</Heading>
      <div>
        {stories.map(
          (story) =>
            story && (
              <>
                <Subheading>{story?.name || ''}</Subheading>
                <Markdown>
                  {story.parameters['docs']?.description?.story || ''}
                </Markdown>
                <Canvas key={story.id} of={story.moduleExport} />
                <Controls
                  key={story.id}
                  of={story.moduleExport}
                  include={[
                    ...(story.initialArgs
                      ? Object.keys(story.initialArgs)
                      : []),
                  ]}
                />
              </>
            )
        )}
      </div>
      <Source />
    </>
  );
};

Hope this helps a bit!

PS: If you dont want to show some auto generated args in the controls tables (like private, protected properties, properties with internal tag (or just set at: ignore in the jsdoc) or angular lifecycle properties like ngOnInit, just add these flags to the compodoc options in angular.json:

--disablePrivate | Do not show private in generated documentation
--disableProtected | Do not show protected in generated documentation
--disableInternal | Do not show @internal in generated documentation
--disableLifeCycleHooks | Do not show Angular lifecycle hooks in generated documentation

[scurk1415]

Your solution worked like a charm! Thank you!!!
I went with the custom component approach and I did make a small modification to it, but otherwise it was perfect 👍

Some instructions if someone else needs a solution like this:

1. Add "jsx": "react" to the compilerOptions of the tsconfig.json in the .storybook directory.
2. Rename preview.ts to preview.tsx
3. Add docs property to the parameters in the preview.tsx

import React from 'react'; // also add this

const preview: Preview = {
  parameters: {
    ...
    docs: {
      page: () => (
        <>
          <Title />
          <Subtitle />
          <Description />
          <Primary />
          <Controls />
          <MyStories /> // Custom component like described above
        </>
      ),
    },
    ...
  }
};

My own modifications:

1. Changed the code above from (story.initialArgs):

<Controls
                  key={story.id}
                  of={story.moduleExport}
                  include={[
                    ...(story.initialArgs
                      ? Object.keys(story.initialArgs)
                      : []),
                  ]}
                />

to (story.moduleExport.args):

<Controls
                  key={ story.id }
                  of={ story.moduleExport }
                  include={ [
                    ...(story.moduleExport.args
                      ? Object.keys(story.moduleExport.args)
                      : []),
                  ] }
                />

Because story.initialArgs also displayed the properties from the meta. And I only wanted properties from the story args. I found this easier and more maintainable than setting exclude/include for the controls.

2. Created a primary story (not displayed in docs or sidebar), needs to be the first story in the file!

export const Primary: Story = {
  tags: ['!autodocs', '!dev'],
};

Because if the first (primary) story was something else then changing the controls/args of the story also changed the properties of the Primary code-block

[smlimasu]

Thank you, and thank you for providing such a detailed guide of the additional setup! I'm glad it works!