Decorators and Parameters

Decorators and parameters are powerful features that let you customize how stories are rendered and configured. Decorators wrap your components with additional markup or context, while parameters control Storybook’s behavior and addon configuration.

Decorators

Decorators are wrapper components that add extra rendering context to your stories. They’re useful for:

Adding providers (theme, navigation, state management)
Wrapping components in layout containers
Adding common UI elements (backgrounds, padding, safe areas)
Simulating different device states

Story-Level Decorators

Apply decorators to individual stories for specific rendering requirements:

import type { Meta, StoryObj } from '@storybook/react-native';
import { View } from 'react-native';
import { Button } from './Button';

const meta = {
  component: Button,
} satisfies Meta<typeof Button>;

export default meta;

type Story = StoryObj<typeof meta>;

export const Centered: Story = {
  decorators: [
    (Story) => (
      <View style={{ alignItems: 'center', justifyContent: 'center', flex: 1 }}>
        <Story />
      </View>
    ),
  ],
  args: {
    title: 'Centered Button',
  },
};

Component-Level Decorators

Define decorators at the meta level to apply them to all stories for a component:

import type { Meta, StoryObj } from '@storybook/react-native';
import { View } from 'react-native';
import { Button } from './Button';

const meta = {
  component: Button,
  decorators: [
    (Story) => (
      <View style={{ alignItems: 'center', justifyContent: 'center', flex: 1 }}>
        <Story />
      </View>
    ),
  ],
} satisfies Meta<typeof Button>;

export default meta;

type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: { title: 'Sign In' },
};

export const Secondary: Story = {
  args: { title: 'Create Account', variant: 'secondary' },
};

Global Decorators

Apply decorators to all stories in your project by adding them to .rnstorybook/preview.tsx:

// .rnstorybook/preview.tsx
import type { Preview } from '@storybook/react-native';
import { View } from 'react-native';
import { withBackgrounds } from '@storybook/addon-ondevice-backgrounds';

const preview: Preview = {
  decorators: [
    withBackgrounds,
    (Story) => (
      <View style={{ flex: 1, padding: 16 }}>
        <Story />
      </View>
    ),
  ],
};

export default preview;

Decorators are applied in order: global decorators first, then component-level, then story-level. Each decorator wraps the previous one.

Common Decorator Patterns

Theme Provider
Safe Area
Layout Container
Navigation

import { ThemeProvider } from './theme';

const withTheme = (Story) => (
  <ThemeProvider theme={darkTheme}>
    <Story />
  </ThemeProvider>
);

const meta = {
  component: MyComponent,
  decorators: [withTheme],
} satisfies Meta<typeof MyComponent>;

import { SafeAreaProvider } from 'react-native-safe-area-context';

const withSafeArea = (Story) => (
  <SafeAreaProvider>
    <Story />
  </SafeAreaProvider>
);

const meta = {
  component: MyComponent,
  decorators: [withSafeArea],
} satisfies Meta<typeof MyComponent>;

import { View, StyleSheet } from 'react-native';

const withPadding = (Story) => (
  <View style={styles.container}>
    <Story />
  </View>
);

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 20,
    backgroundColor: '#f5f5f5',
  },
});

const meta = {
  component: MyComponent,
  decorators: [withPadding],
} satisfies Meta<typeof MyComponent>;

import { NavigationContainer } from '@react-navigation/native';

const withNavigation = (Story) => (
  <NavigationContainer>
    <Story />
  </NavigationContainer>
);

const meta = {
  component: MyScreen,
  decorators: [withNavigation],
} satisfies Meta<typeof MyScreen>;

Parameters

Parameters are static metadata about your stories. They control Storybook’s features and configure addons.

Story-Level Parameters

Configure parameters for individual stories:

import type { StoryObj, Meta } from '@storybook/react-native';
import { Text, StyleSheet } from 'react-native';

const Background = () => (
  <Text style={styles.text}>Change background color via Addons -&gt; Background</Text>
);

const styles = StyleSheet.create({
  text: { color: 'black' },
});

const meta = {
  component: Background,
} satisfies Meta<typeof Background>;

export default meta;

type Story = StoryObj<typeof meta>;

export const Warm: Story = {
  globals: {
    backgrounds: { value: 'warm' },
  },
};

Component-Level Parameters

Define parameters at the meta level to apply them to all stories:

import type { Meta, StoryObj } from '@storybook/react-native';
import { ActionButton } from './Actions';

const meta = {
  component: ActionButton,
  parameters: {
    notes: `
# Button

This is a button component.
You use it like this:

\`\`\`tsx    
<Button 
      text="Press me!" 
      onPress={() => console.log('pressed')} 
/>
\`\`\`
`,
  },
} satisfies Meta<typeof ActionButton>;

export default meta;

Global Parameters

Configure parameters for all stories in .rnstorybook/preview.tsx:

// .rnstorybook/preview.tsx
import { Appearance } from 'react-native';
import type { Preview } from '@storybook/react-native';

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: '^on[A-Z].*' },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
    options: {
      storySort: {
        method: 'alphabetical',
        includeNames: true,
        order: ['ControlExamples', ['ControlExample'], 'InteractionExample'],
      },
    },
    hideFullScreenButton: false,
    noSafeArea: false,
    layout: 'padded', // fullscreen, centered, padded
    storybookUIVisibility: 'visible', // visible, hidden
    backgrounds: {
      options: {
        dark: { name: 'dark', value: '#333' },
        light: { name: 'plain', value: '#fff' },
        app: { name: 'app', value: '#eeeeee' },
      },
    },
  },
  initialGlobals: {
    backgrounds: { 
      value: Appearance.getColorScheme() === 'dark' ? 'dark' : 'plain' 
    },
  },
};

export default preview;

Common Parameters

Actions

Configure which props trigger action logging:

parameters: {
  actions: { 
    argTypesRegex: '^on[A-Z].*'  // Match all props starting with 'on'
  },
}

Controls

Customize the controls addon behavior:

parameters: {
  controls: {
    matchers: {
      color: /(background|color)$/i,  // Auto-detect color props
      date: /Date$/,                   // Auto-detect date props
    },
  },
}

Backgrounds

Define available background colors for the backgrounds addon:

parameters: {
  backgrounds: {
    default: 'warm',
    values: [
      { name: 'warm', value: 'hotpink' },
      { name: 'cool', value: 'deepskyblue' },
      { name: 'white', value: 'white' },
      { name: 'black', value: 'black' },
    ],
  },
}

Notes

Add markdown documentation to your stories:

const meta = {
  component: NotesExample,
  parameters: {
    notes: `
# H1

## H2

This is a paragraph that can span multiple lines.

Inline content can be **strong**, _emphasized_, ~~struck out~~, \`code\`, or a [hyperlink](http://example.com).

- Unordered lists
- Work great

1. Ordered lists
2. Also work

\`\`\`tsx
Code fences are blocks of monospace text
\`\`\`

> Block quotes are blocks of normal text
> where **inline** markup is possible
`,
  },
} satisfies Meta<typeof NotesExample>;

Layout

Control how stories are rendered in the canvas:

parameters: {
  layout: 'padded',  // 'fullscreen' | 'centered' | 'padded'
}

Story Sorting

Control the order stories appear in the sidebar:

parameters: {
  options: {
    storySort: {
      method: 'alphabetical',
      includeNames: true,
      order: [
        'Introduction',
        'Components',
        ['Button', 'Input', 'Card'],
        'Examples',
      ],
    },
  },
}

Combining Decorators and Parameters

Decorators and parameters work together to create rich story environments:

import type { Meta, StoryObj } from '@storybook/react-native';
import { View } from 'react-native';
import { ThemeProvider } from './theme';
import { MyComponent } from './MyComponent';

const meta = {
  component: MyComponent,
  decorators: [
    (Story) => (
      <ThemeProvider>
        <View style={{ padding: 16 }}>
          <Story />
        </View>
      </ThemeProvider>
    ),
  ],
  parameters: {
    backgrounds: {
      options: {
        dark: { name: 'Dark', value: '#1a1a1a' },
        light: { name: 'Light', value: '#ffffff' },
      },
    },
    notes: `
# MyComponent

A versatile component with theme support.
    `,
  },
} satisfies Meta<typeof MyComponent>;

export default meta;

Use decorators for visual/structural changes and parameters for configuration. This separation keeps your stories clean and maintainable.

Best Practices

Use global decorators sparingly: Only add decorators that truly apply to all stories
Keep decorators simple: Complex decorators can make debugging difficult
Document parameters: Add comments explaining why parameters are set
Reuse decorators: Extract common decorators into shared functions
Test with and without decorators: Ensure components work independently

Get Started

Installation

Core Concepts

Configuration

Addons

Guides

Migration

Decorators

Story-Level Decorators

Component-Level Decorators

Global Decorators

Common Decorator Patterns

Parameters

Story-Level Parameters

Component-Level Parameters

Global Parameters

Common Parameters

Actions

Controls

Backgrounds

Notes

Layout

Story Sorting

Combining Decorators and Parameters

Best Practices

Next Steps

Addons

Testing with Stories

Build docs developers (and LLMs) love

Get Started

Installation

Core Concepts

Configuration

Addons

Guides

Migration

​Decorators

​Story-Level Decorators

​Component-Level Decorators

​Global Decorators

​Common Decorator Patterns

​Parameters

​Story-Level Parameters

​Component-Level Parameters

​Global Parameters

​Common Parameters

​Actions

​Controls

​Backgrounds

​Notes

​Layout

​Story Sorting

​Combining Decorators and Parameters

​Best Practices

​Next Steps

Addons

Testing with Stories

Build docs developers (and LLMs) love

Decorators

Story-Level Decorators

Component-Level Decorators

Global Decorators

Common Decorator Patterns

Parameters

Story-Level Parameters

Component-Level Parameters

Global Parameters

Common Parameters

Actions

Controls

Backgrounds

Notes

Layout

Story Sorting

Combining Decorators and Parameters

Best Practices

Next Steps