React Native Storybook Stories

@storybook/react-native v10 と Component Story Format (CSF) を使用して React Native コンポーネントのストーリーを記述します。

クイックスタート

最小限のストーリーファイル:

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

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

export default meta;
type Story = StoryObj<typeof meta>;

export const Basic: Story = {
  args: {
    label: 'Hello',
  },
};

ファイル規約

• 名前: ComponentName.stories.tsx (コンポーネントと同じディレクトリに配置)
• Meta と StoryObj を @storybook/react-native からインポート
• デフォルトエクスポート: satisfies Meta<typeof Component> を持つ meta オブジェクト
• 名前付きエクスポート: UpperCamelCase のストーリー名で StoryObj<typeof meta> として型付け
• props には args を使用、コントロール設定には argTypes を使用、アドオン設定には parameters を使用
• カスタムレンダー関数には render を使用、ラッパーには decorators を使用

ストーリーパターン

共有 args を持つ複数のストーリー

export const Primary: Story = {
  args: { variant: 'primary', title: 'Click me' },
};

export const Secondary: Story = {
  args: { ...Primary.args, variant: 'secondary' },
};

カスタムレンダー関数

export const WithScrollView: Story = {
  render: (args) => (
    <ScrollView>
      <MyComponent {...args} />
    </ScrollView>
  ),
};

フック付きレンダー (名前付き関数である必要があります)

export const Interactive: Story = {
  render: function InteractiveRender() {
    const [count, setCount] = useReducer((s) => s + 1, 0);
    return <Counter count={count} onPress={setCount} />;
  },
};

アクション (コールバックのモック)

import { fn } from 'storybook/test';

const meta = {
  component: Button,
  args: { onPress: fn() },
} satisfies Meta<typeof Button>;

または argTypes 経由:

argTypes: { onPress: { action: 'pressed' } },

カスタムストーリー名

export const MyStory: Story = {
  storyName: 'Custom Display Name',
  args: { label: 'Hello' },
};

カスタムタイトル / ネスティング

const meta = {
  title: 'NestingExample/Message/Bubble',
  component: MyComponent,
} satisfies Meta<typeof MyComponent>;

コントロール & ArgTypes

コントロール種別の完全なリファレンスについては references/controls.md を参照してください。

よくあるパターン:

const meta = {
  component: MyComponent,
  argTypes: {
    // セレクトドロップダウン
    size: {
      options: ['small', 'medium', 'large'],
      control: { type: 'select' },
    },
    // 範囲スライダー
    opacity: {
      control: { type: 'range', min: 0, max: 1, step: 0.1 },
    },
    // カラーピッカー
    color: { control: { type: 'color' } },
    // 条件付きコントロール (`advanced` arg が true の場合のみ表示)
    padding: { control: 'number', if: { arg: 'advanced' } },
  },
} satisfies Meta<typeof MyComponent>;

自動検出: TypeScript プロパティ型は自動的にコントロールにマップされます (string -> テキスト、boolean -> ブール値、ユニオン型 -> セレクト、number -> 数値)。

パラメータ

アドオンパラメータ

parameters: {
  // Notes アドオンタブのマークダウンドキュメント
  notes: `# MyComponent\nUsage: \`<MyComponent label="hi" />\``,
  // Backgrounds アドオン用の背景オプション
  backgrounds: {
    default: 'dark',
    values: [
      { name: 'light', value: 'white' },
      { name: 'dark', value: '#333' },
    ],
  },
},

RN 固有の UI パラメータ

パラメータ	型	説明
noSafeArea	boolean	上部セーフエリアのパディングを削除します。これを使用する場合、Storybook がセーフエリアのパディングを提供しなくなるため、コンポーネント自体がセーフエリアを処理する必要があります。SafeAreaView の代わりに useSafeAreaInsets() を使用し、インセットをコンテナの paddingTop/paddingBottom として適用し、スクロール可能なコンテンツの場合は SafeAreaView でラップする代わりに contentContainerStyle パディングを使用します。
storybookUIVisibility	'visible' | 'hidden'	UI の初期表示状態
hideFullScreenButton	boolean	フルスクリーン切り替えボタンを非表示にします
layout	'padded' | 'centered' | 'fullscreen'	ストーリーコンテナレイアウト

パラメータはストーリー、メタ (コンポーネント)、またはグローバル (preview.tsx) レベルで設定できます。

デコレータ

ストーリーをプロバイダー、レイアウト、またはコンテキストでラップします:

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

グローバルデコレータは .rnstorybook/preview.tsx に記述します:

import { withBackgrounds } from '@storybook/addon-ondevice-backgrounds';
import type { Preview } from '@storybook/react-native';

const preview: Preview = {
  decorators: [withBackgrounds],
  parameters: {
    actions: { argTypesRegex: '^on[A-Z].*' },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
    backgrounds: {
      default: 'plain',
      values: [
        { name: 'plain', value: 'white' },
        { name: 'dark', value: '#333' },
      ],
    },
  },
};

export default preview;

設定

.rnstorybook/main.ts

import type { StorybookConfig } from '@storybook/react-native';

const main: StorybookConfig = {
  stories: ['../components/**/*.stories.?(ts|tsx|js|jsx)'],
  deviceAddons: [
    '@storybook/addon-ondevice-controls',
    '@storybook/addon-ondevice-backgrounds',
    '@storybook/addon-ondevice-actions',
    '@storybook/addon-ondevice-notes',
  ],
  framework: '@storybook/react-native',
};

export default main;

ストーリーグロブは複数ディレクトリ設定用のオブジェクト形式もサポートしています:

stories: [
  '../components/**/*.stories.?(ts|tsx|js|jsx)',
  { directory: '../other_components', files: '**/*.stories.?(ts|tsx|js|jsx)' },
],

ポータブルストーリー (テスト)

Jest テストでストーリーを再利用します:

import { render, screen } from '@testing-library/react-native';
import { composeStories } from '@storybook/react';
import * as stories from './Button.stories';

const { Primary, Secondary } = composeStories(stories);

test('renders primary button', () => {
  render(<Primary />);
  expect(screen.getByText('Click me')).toBeTruthy();
});

// テスト内で args をオーバーライド
test('renders with custom props', () => {
  render(<Primary title="Custom" />);
  expect(screen.getByText('Custom')).toBeTruthy();
});

単一のストーリーの場合は composeStory を使用します:

import { composeStory } from '@storybook/react';
import meta, { Primary } from './Button.stories';

const PrimaryStory = composeStory(Primary, meta);

Jest セットアップファイルでテスト用のグローバルアノテーションを設定します:

// setup-portable-stories.ts
import { setProjectAnnotations } from '@storybook/react';
import * as previewAnnotations from '../.rnstorybook/preview';
setProjectAnnotations(previewAnnotations);

アドオンの概要

アドオン	パッケージ	目的
Controls	@storybook/addon-ondevice-controls	props をインタラクティブに編集
Actions	@storybook/addon-ondevice-actions	コンポーネント操作をログ出力
Backgrounds	@storybook/addon-ondevice-backgrounds	ストーリーの背景を変更
Notes	@storybook/addon-ondevice-notes	マークダウンドキュメントを追加