Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time

Psammead - BBC Package Library - 🚨 NO LONGER MAINTAINED 🚨

We have recently migrated most of our Psammead components (except for BBC Web Vitals) to a legacy folder in our Single Page Application called Simorgh.

Any open source contributions to these components should now be made via the Simorgh repo as they are no longer being maintained in the Psammead repo.

Known Vulnerabilities Maintainability Test Coverage Storybook PRs Welcome

Psammead is a package library which contains a mixture of components, containers and utilities.

Psammead packages are split into:

  • Components - GEL-compliant presentational React components. They are ready for use out of the box, regardless of data source.
  • Containers - Functional components for optional use with presentational components of the same name.
  • Utilities - Commonly shared Psammead dependencies, fundamentals to aid building additional GEL-compliant components, and aditional packages for use in building SPAs.

Documentation index

Please familiarise yourself with our:

NB there is further documentation colocated with relevant packages and code. The above list is an index of the top-level documentation of our repo (and our sibling repo Simorgh).

🎁 Getting Started

✈️ Clone this repository

git clone

Install Yarn

The Psammead project uses Yarn for package management. It is recommended to install Yarn through the npm package manager, which comes bundled with Node.js when you install it on your system. To install Yarn, run this command:

npm install --global yarn

🔨 Setup Local Environment

cd psammead && yarn install:packages

N.B. When merging branches, the yarn install:packages command should be favoured over yarn install. More details available here.

🏃 Run tests

Install dependencies locked to yarn.lock:

yarn install --immutable

(NB: You can't reliably run the jest tests when the packages are linked locally, as they may have been linked across breaking changes. Running yarn install --immutable resets all links. To update snapshots within unit tests, run yarn test:unit -- -u.)

Run the component tests:

yarn test

This runs Jest across any packages matching this glob pattern: packages/components/**/*.test.jsx. It also runs each package's yarn test command if it is defined

🏃 Run Storybook

yarn storybook

NB, we've defined global styles (normalize, box-sizing, Reith font) in the Storybook config so that components render as expected.

👷 Build Packages/Components

yarn build

💻 Developing with Psammead

Learn how to use Psammead components in your own project.

📊 Support levels

We strive for components to conform to the following minimum levels of support, but please check each component's individual README.

Browser support

Browser Lowest version
Safari 9
Chrome 53
Edge 37
Firefox 45
IE 11
Opera 40
Opera Mini 18
Android Browser 7
Android Chrome 53
Android Firefox 49
IOS Safari 10

Note that these browser support levels have been defined by usage statistics for BBC News and BBC Persian.

Assistive Technology Support

Software Version Type Browser
ZoomText Latest screen magnifier Internet Explorer 11
Dragon NaturallySpeaking 13 speech recognition Internet Explorer 11
JAWS 17 screen reader Internet Explorer 11
Read&Write Latest screen reader Internet Explorer 11
VoiceOver Latest screen reader Safari on iOS
NVDA Latest screen reader Firefox on Windows

Testing instructions for each assistive technology, including priority categories.

🚀 Publishing Packages (only available for BBC staff as we publish via our corporate npm)

⚙️ Setting up your npm account

  • Create an npm account with your bbc email address.
  • In your npm profile settings, set up Two Factor Authentication. Enable it for authorization and publishing
  • Back up your recovery codes for your account
  • Join the BBC npm org by following the process here: When you're added to the org and signed in, you should be able to see all public and private @bbc packages here:

🎈 Publishing a package

Packages are published on merge into the latest branch via our CI process. The process defaults to publishing with public access and a tag of latest, however this can be overridden using configuration on your package json.

To stop your package from publishing to NPM add the following value to your package.json

"private": true,

The access and tag of the release can be overridden from the default values by adding the following values to your package.json

"publishConfig": {
  "access": "restricted",
  "tag": "alpha",

The access value is restricted by NPM and can only be the values public and restricted.

🎢 Deploying Storybook

The Psammead Storybook is hosted on GitHub pages at It is currently deployed via a local script that builds Storybook to the gh-pages git branch which is used by GitHub pages.

yarn deploy-storybook

NB, this automatically pushes to the 'gh-pages' branch, which deploys to the live GitHub pages site. Please only run this script on the latest branch.

The name?

Image of the Psammead from the BBC TV program Five Children and It (2004)

Pronounced as sam-me-ad 'sæmiː|æd

"The Psammead, also known as Sand Fairy, is a sapient magical creature once encountered by five children in a gravel pit".

It MIGHT stand for:

Perfectly sharable atomically modular magically engineered abstract doodads

Or it might be named Psammead to follow the mythical creature theme of related repos.

We'll let you decide!


React component library for BBC World Service and more



Code of conduct

Security policy





No packages published