9.0.17 • Public • Published

psammead-storybook-helpers - Known Vulnerabilities Dependency Status peerDependencies Status GitHub license npm version PRs Welcome

This package provides a collection of common values that are used in storybook by the Psammead components.


TEXT_VARIANTS - A list of text samples in different languages, with the script and direction that should be used for that language.

themes - An object containing the Storybook themes we use.

withServicesKnob - Is a function that returns a storybook decorator function that adds a Select a service dropdown to the knobs panel. When a service is selected from the dropdown it does 2 things:

  1. Provides the decorated stories with the following properties that can be passed into components:
  • text: A short string of text in the language of the chosen service.
  • longText: A long string of text in the language of the chosen service (we can use this to stress test components).
  • dir: The reading directionality of the chosen service e.g. ltr or rtl.
  • script: The chosen service's script typography settings e.g. the font-size and line-heights.
  • service: The name of the chosen service e.g. arabic.
  • variant: The variant value of a chosen service, e.g serbianLat will have variant lat. Non variant service will default to default.
  • articlePath: A path to an article in the relevant service.
  • selectedService: The name of the selected service as it appears in the dropdown of available services.
  1. Toggles the layout directionality of the chosen service.

The withServicesKnob function accepts an options argument with 2 properties:

  • defaultService(String): The default selected service of the services dropdown e.g. arabic. The default is news.
  • services(Array): A list of services that the dropdown will display. The default is all services.

buildRTLSubstories - a function to create right-to-left variants of stories as substories. Internally it uses the withServicesKnob to set the default service as arabic.

The buildRTLSubstories function accepts 2 arguments.

  • storyKind(String) - This is the story kind that you want you want to create RTL substories from. This will normally be the first argument you pass into storiesOf e.g. storiesOf('Components/Paragraph', module). This parameter is required.
  • options(Object) - Available options:
    • include(Array) - A list of specific story names to create RTL substories of. If this is not provided then all stories will have RTL substories.


npm install @bbc/psammead-storybook-helpers --save-dev



import { select } from '@storybook/addon-knobs';
import { TEXT_VARIANTS } from '@bbc/psammead-storybook-helpers';

const label = 'Languages';
const defaultValue = 'This is a caption';
const groupIdentifier = 'CAPTION VARIANTS';

  {select(label, TEXT_VARIANTS, TEXT_VARIANTS.news, groupIdentifier).text}


storiesOf('Components/Paragraph', module)
  .addDecorator(withServicesKnob()) // default selected service is `news`
  .add('A paragraph with English text', ({ text, script, service }) => (
    <Paragraph script={script} service={service}>

To set a default service:

storiesOf('Components/Paragraph', module)
      defaultService: 'arabic',
      services: ['news', 'arabic', 'amharic'],
  ) // default selected service is `arabic` and the available services in the dropdown are `news`, `arabic`, `amharic`
  .add('A paragraph with Arabic text', ({ text, script, service }) => (
    <Paragraph script={script} service={service}>

If you want to add this decorator to a single story rather than a series of stories as documented above, perhaps because you need each story to have a different default service, then you need to decorate each story directly instead of using the addDecorator method. An example of how you could write this is shown below:

const arabicServiceDecorator = withServicesKnob({
  defaultService: 'arabic',

const pashtoServiceDecorator = withServicesKnob({
  defaultService: 'pashto',

storiesOf('Components/Paragraph', module)
  .add('A paragraph with Arabic text', () =>
    arabicServiceDecorator(({ text, script, service }) => (
      <Paragraph script={script} service={service}>
  .add('A paragraph with Pashto text', () =>
    pashtoServiceDecorator(({ text, script, service }) => (
      <Paragraph script={script} service={service}>

You can include links to articles in the relevant services and variants

const BASE_URL = 'https://www.bbc.com';

storiesOf('Components/Paragraph/Link', module)
  .addDecorator(withServicesKnob()) // default selected service is `news`
    'A paragraph with an inline link to an article',
    ({ text, script, service, articlePath }) => (
      <Paragraph script={script} service={service}>
        <InlineLink href={`${BASE_URL}${articlePath}`}>{text}</InlineLink>

The above example dismisses the use of the addDecorator method and decorates the story directly.


import { buildRTLSubstories } from '@bbc/psammead-storybook-helpers';

// create RTL variants of all stories of a kind
import { buildRTLSubstories } from '@bbc/psammead-storybook-helpers';

// create RTL variants of specific stories of a kind
buildRTLSubstories('Components/Paragraph', {
  include: ['containing an inline link'],


When adding a new export to this utility package the export tests also need to be updated. When removing an exisiting export from this utility package the export tests need to be updated and the package version requires a major change (EG: 1.2.1 -> 2.0.0) as this would be considered a breaking change due to functionality being removed.

Psammead is completely open source. We are grateful for any contributions, whether they be new components, bug fixes or general improvements. Please see our primary contributing guide which can be found at the root of the Psammead respository.

Code of Conduct

We welcome feedback and help on this work. By participating in this project, you agree to abide by the code of conduct. Please take a moment to read it.


Psammead is Apache 2.0 licensed.

Package Sidebar


npm i @bbc/psammead-storybook-helpers

Weekly Downloads






Unpacked Size

164 kB

Total Files


Last publish


  • eagerterrier_bbc
  • bbc-online