Skip to content
React component library for BBC World Service and more
JavaScript Other
Branch: latest
Clone or download
jroebu14 Merge pull request #2166 from bbc/remove-async-keyword
remove async keyword from test helpers
Latest commit 4e1b056 Sep 17, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.dependabot Update .dependabot/config.yml Sep 9, 2019
.github revise names Aug 23, 2019
.storybook Fix storybook Sep 16, 2019
.yeoman increase jestTimemout and add a ls Sep 10, 2019
documentation added chromaticqa doc Sep 3, 2019
lib/stylelint comment about potential to remove custom processor Jul 15, 2019
packages fix version bump in changelog Sep 17, 2019
scripts Merge branch 'latest' into alpha-bumps Sep 9, 2019
.eslintignore eslint ignore packages/utilities/psammead-locales/moment/*.jsx and *.… Sep 12, 2019
.eslintrc.js update eslint-config-airbnb to 18.0.1 Sep 2, 2019
.gitattributes Adds gitattributes to enforce line endings Nov 22, 2018
.gitignore 🚀 Log publishes Jul 22, 2019
.npmrc Upgrading the node version Jun 17, 2019
.nvmrc Upgrading the nvmrc Sep 9, 2019
.prettierrc Add eslintrc prettierrc and install dependancies Nov 22, 2018
.stylelintrc Remove @babel/plugin-proposal-export-namespace-from. Revert changes t… Aug 20, 2019 bump dependency Sep 17, 2019 behaviour Jun 13, 2019 Update Aug 23, 2019
Jenkinsfile Upgrading to node 10.16.3 Sep 9, 2019
LICENSE adds Apache LICENSE, fixes #7 Nov 22, 2018
Makefile 🚀 Make talos findable again Sep 4, 2019 Merge branch 'latest' into ScriptsAudit Sep 2, 2019
babel.config.js Remove @babel/plugin-proposal-export-namespace-from. Revert changes t… Aug 20, 2019
lerna.json Ensure lerna bootstrap command does not update the package-lock files Feb 26, 2019
package-lock.json bump dependency Sep 17, 2019
package.json bump dependency Sep 17, 2019

Psammead - BBC Component Library

Known Vulnerabilities dependencies Status devDependencies Status Maintainability Test Coverage Storybook PRs Welcome

Psammead is a GEL-compliant React component library for the BBC, built on styled-components.

Psammead packages are split into:

  • Components - GEL-compliant presentational React components, ready for use out of the box, regardless of data source.
  • Utilities - Commonly shared Psammead dependencies, and fundamentals to aid building additional GEL-compliant components.

🎁 Getting Started

✈️ Clone this repository

git clone

🔨 Setup Local Environment

cd psammead && npm run install:packages

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

🏃 Run tests

Install dependencies locked to package-lock.json:

npm run ci:packages

(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 npm run ci:packages resets all links. To update snapshots within unit tests, run npm run test:unit -- -u.)

Run the component tests:

npm test

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

✏️ Create a new package

npm run create:package

🏃 Run Storybook

npm run 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

npm run 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

⚙️ 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.

npm run 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.


Psammead is currently maintained by developers in the BBC Simorgh teams. If you want to open an issue, please add it to our issues page.

Contact us by email on, or find us on Slack at #si_repo-psammead in the bbcnews workspace.

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!

You can’t perform that action at this time.