UI components & Storybook

We use Storybook as a UI library and UI dev environment. You can refer to Storybook to find UI components that are already in use in the project and you can potentially use yourself, rather than building them again. If you are building a new UI component, Storybook is a great way to build it in isolation and later on display it for the next person to find. Think of it like test-driven development but for UI!

Browsing components

We publish our storybooks using Chromatic: replacing “branch” in the following link with a branchname will give a link to the storybook for that branch:

https://<branch>--62e115310aef0868687b2322.chromatic.com

(For clickability, here’s a link for the storybook for the main branch.)

Creating components

While running ./devrun.sh, browse to http://localhost:9001/.

There's not a lot that's storybook-specific about components, you will be working with the same standard React components that you would use in the page. In fact, you can add components you've already built to it! To display a component in Storybook, first create the stories for it, create as many as the cases you want to test:

📄 /stories/checkout/Ticker.stories.tsx

import React from 'react';
import type { TickerProps } from 'components/ticker/ticker';
import { Ticker } from 'components/ticker/ticker';

export default {
	title: 'Checkouts/Ticker',
	component: Ticker,
	argTypes: {
		appearance: {
			control: {
				type: 'radio',
				options: ['light', 'dark'],
			},
		},
		onGoalReached: { action: 'goal reached' },
	},
};

function Template(args: TickerProps) {
	return <Ticker {...args} />;
}

Template.args = {} as TickerProps;

export const PeopleTicker = Template.bind({});

PeopleTicker.args = {
	total: 200000,
	goal: 200000,
	end: 250000,
	countType: 'people',
	endType: 'unlimited',
	countryGroupId: 'AUDCountries',
	headline: 'End of year campaign',
};

export const MoneyTicker = Template.bind({});

MoneyTicker.args = {
	total: 50000,
	goal: 200000,
	end: 230000,
	countType: 'money',
	endType: 'hardstop',
	countryGroupId: 'UnitedStates',
	headline: 'End of year campaign',
};

There's no hard rule about what goes in a story. You might want to see all you states at once or you might want to isolate them. Both are valid uses and it is encouraged that you do what you feel works best for showcasing a particular component.

Once you have written your stories you can continue to build your component inline in the page it'll be displayed or you can develop it in the Storybook UI itself. It has hot module reload and is blazing fast as it's not bringing along any code it doesn't need. Make sure you check the 'Accessibility' tab in case our Axe integration has detected any accessibility issues with your component.

For details on how to add controls to stories and more advanced topics, see the Storybook docs.