배경 (Backgrounds)
React | Vue | Angular | Web Components | 그 외(More)
배경(Backgrounds) 기능은 스토리북 UI 안에서 스토리가 렌더링될 때 그 뒤에 깔리는 배경색을 설정할 수 있게 해줍니다:
설정하기 (Configuration)
기본적으로 이 기능에는 밝은색(light)과 어두운색(dark), 두 가지 배경이 포함되어 있어요.
하지만 이 두 가지에만 얽매일 필요는 없습니다! .storybook/preview.js|ts 파일의 backgrounds 파라미터(parameter)를 이용해서 여러분만의 배경색 세트를 자유롭게 설정할 수 있거든요.
options 속성으로 선택 가능한 배경색 목록을 정의하고, initialGlobals 속성으로 처음 켜졌을 때 보여줄 기본 배경색을 지정할 수 있습니다:
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { Preview } from '@storybook/your-framework';
const preview: Preview = {
parameters: {
backgrounds: {
options: {
// 👇 기본으로 제공되는 옵션 덮어쓰기
dark: { name: 'Dark', value: '#333' },
light: { name: 'Light', value: '#F7F9F2' },
// 👇 나만의 색상 추가하기
maroon: { name: 'Maroon', value: '#400' },
},
},
},
initialGlobals: {
// 👇 처음 열렸을 때 보여줄 기본 배경색 설정
backgrounds: { value: 'light' },
},
};
export default preview;특정 스토리만 배경색 지정하기 (Defining the background for a story)
보통은 툴바에 있는 미리 정의된 배경색 목록에서 클릭해서 배경색을 바꿉니다. 하지만 특정 스토리(혹은 특정 컴포넌트의 모든 스토리)가 켜질 때마다 '무조건 이 배경색으로 시작해라!'라고 못 박고 싶을 때가 있죠? 그럴 땐 globals 옵션을 사용하면 됩니다:
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
import { Button } from './Button';
const meta = {
component: Button,
globals: {
// 👇 Button 컴포넌트의 모든 스토리에 회색 배경을 기본으로 깔아줍니다.
backgrounds: { value: 'gray', grid: false },
},
} satisfies Meta<typeof Button>;
export default meta;
type Story = StoryObj<typeof meta>;
export const OnDark: Story = {
globals: {
// 👇 이 스토리 하나만 콕 집어서 'dark' 배경으로 덮어씁니다.
backgrounds: { value: 'dark' },
},
};ℹ️ 참고: globals를 사용해서 컴포넌트나 스토리의 배경색을 강제로 고정해버리면, 그 색상이 찰싹 달라붙어서 툴바 버튼을 눌러도 색상이 바뀌지 않게 됩니다. 스토리가 반드시 특정한 배경색 위에서 렌더링되어야만 할 때 유용한 기능이에요.
설정 확장하기 (Extending the configuration)
파라미터 상속(parameter inheritance)의 마법을 이용하면 컴포넌트 단위로나 스토리 단위로도 배경 설정을 요리조리 바꿀 수 있습니다.
목록에 나오는 배경색들을 바꾸고 싶다면 options 속성을 사용하세요. 예를 들어, Button 컴포넌트의 모든 스토리에 기본값 대신 다른 색상 옵션들을 주려면 이렇게 합니다:
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
import { Button } from './Button';
const meta = {
component: Button,
parameters: {
backgrounds: {
options: {
// 👇 기본 'dark' 옵션을 덮어씁니다.
dark: { name: 'Dark', value: '#000' },
// 👇 새로운 색상을 하나 추가합니다.
gray: { name: 'Gray', value: '#CCC' },
},
},
},
} satisfies Meta<typeof Button>;
export default meta;
type Story = StoryObj<typeof meta>;
export const ExperimentalFeatureStory: Story = {
// 👇 특정 스토리에만 적용하고 싶다면 똑같이 parameters.backgrounds.options를 적어주면 됩니다.
parameters: {
backgrounds: {
options: {
// ...
}
}
}
};배경 끄기 (Disable backgrounds)
어떤 스토리에선 배경색 바꾸는 기능 자체가 필요 없을 수도 있죠. 그럴 땐 backgrounds 파라미터에서 기능을 아예 꺼버릴(disable) 수 있습니다:
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
import { Button } from './Button';
const meta = {
component: Button,
} satisfies Meta<typeof Button>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Large: Story = {
parameters: {
backgrounds: { disable: true },
},
};그리드 (Grid)
배경 기능에는 스토리에 격자무늬(Grid)를 띄우는 기능도 포함되어 있습니다. 컴포넌트들 줄이 삐뚤어지지 않고 잘 맞는지 확인할 때 최고죠!
이 기능은 특별히 설정하지 않아도 바로 쓸 수 있지만, 그리드의 모양새(properties)는 여러분 입맛대로 완전히 커스터마이징할 수 있습니다. 아무 값도 주지 않으면 알아서 아래의 기본값들로 그려집니다:
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta } from '@storybook/your-framework';
import { Button } from './Button';
const meta = {
component: Button,
parameters: {
backgrounds: {
grid: {
cellSize: 20,
opacity: 0.5,
cellAmount: 5,
offsetX: 16, // 스토리 layout이 'fullscreen'이면 기본값은 0, 'padded'면 16입니다.
offsetY: 16, // 스토리 layout이 'fullscreen'이면 기본값은 0, 'padded'면 16입니다.
},
},
},
} satisfies Meta<typeof Button>;
export default meta;API
이 모듈은 크게 전역 변수(Globals)와 파라미터(Parameters) 두 가지 방식으로 스토리북 설정에 기여합니다. 모두 backgrounds 네임스페이스 아래에 위치합니다.
전역 변수 (Globals)
grid
타입: boolean
그리드(grid)를 화면에 보여줄지 말지 결정합니다.
value
타입: string
이 값이 설정되면, 스토리에 그 배경색이 찰싹 고정되어 툴바 버튼으로 바꿀 수 없게 됩니다. 반드시 미리 설정해 둔 사용 가능한 색상들(available colors)의 이름(key) 중 하나와 정확히 일치해야 해요.
파라미터 (Parameters)
disable
타입: boolean
이 배경 기능의 동작 자체를 끕니다. 만약 스토리북 전체에서 이 기능을 아예 빼버리고 싶다면, 메인 설정 파일(main.js|ts)에서 기능을 비활성화(disable)하시는 게 낫습니다.
이 파라미터는 보통 전체 프로젝트 수준에서는 꺼두고(true), 특정한 컴포넌트나 스토리에서만 다시 켤 때(false) 요긴하게 쓰입니다.
grid
타입:
{
cellAmount?: number;
cellSize?: number;
disable?: boolean;
offsetX?: number;
offsetY?: number;
opacity?: number;
}배경 그리드(background grid)의 생김새를 결정하는 설정 묶음입니다.
grid.cellAmount
타입: number
기본값: 5
작은 격자 선(minor grid lines)이 큰 격자 칸 안에 몇 개 들어갈지 정합니다.
grid.cellSize
타입: number
기본값: 20
가장 기본이 되는 격자 한 칸의 크기입니다.
grid.disable
타입: boolean
그리드 기능을 끕니다.
grid.offsetX
타입: number
기본값: 스토리 레이아웃(story layout)이 'fullscreen'이면 0, 'padded'면 16
그리드를 가로(x축)로 얼마나 이동시킬지 정합니다.
grid.offsetY
타입: number
기본값: 스토리 레이아웃(story layout)이 'fullscreen'이면 0, 'padded'면 16
그리드를 세로(y축)로 얼마나 이동시킬지 정합니다.
grid.opacity
타입: number
기본값: 0.5
그리드 선의 불투명도를 조절합니다. (0이면 투명, 1이면 완전 불투명)
options
(필수 항목, 위의 설명을 참고하세요)
타입:
{
[key: string]: {
name: string;
value: string;
};
}화면에 보여줄 수 있는 배경색 옵션들의 목록입니다. 어떻게 사용하는지 궁금하시다면 위쪽의 설정하기(Configuration) 예시를 다시 한번 살펴봐 주세요!
이 페이지가 유용했나요? 👍 👎
✍️ 깃허브에서 편집하기 (Edit on Github)
