Skip to content
A babel plugin to add css namespaces (and increase specificity) of styled-component classes.
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
src I accidentally deleted a period at some point that I shouldn't have (#30 Feb 22, 2019
.gitignore Use postcss for better handling of css transformation (#29) Feb 22, 2019
.npmignore Setup initial travis ci config (#4) Feb 26, 2018
.nvmrc Use postcss for better handling of css transformation (#29) Feb 22, 2019
CODEOWNERS Add codeowners & update package location (#3) Feb 26, 2018
yarn.lock Use postcss for better handling of css transformation (#29) Feb 22, 2019


Getting Started

  1. Add the plugin with yarn add @quickbaseoss/babel-plugin-styled-components-css-namespace or npm install @quickbaseoss/babel-plugin-styled-components-css-namespace
  2. Include the plugin in your babel configuration.
"babel": {
  "plugins": [

If you are also using babel-plugin-styled-components, you must place styled-components-css-namespace before styled-components.

"babel": {
  "plugins": [



Without adding options, this plugin will duplicate the class name generated by styled-components as suggested in this issue.

// output
.c0.c0 {
  background-color: blue;

Custom Namespace

You can provide a cssNamespace to use instead of duplicating the class name. Remember to include a DOM element with that class that wraps the styled-component. The cssNamespace takes the form of the selector you want to use to wrap all of your styles with.

"babel": {
  "plugins": [
    ["@quickbaseoss/babel-plugin-styled-components-css-namespace", {"cssNamespace": ".specific .moreSpecific .reallySpecific"}],
// output
.specific .moreSpecific .reallySpecific .c0 {
  background-color: blue;

where .c0 is the class added by styled-components to the element

Upgrade to version 1.0.0

Note that rawCssNamespace was dropped in favor of the single cssNamespace option. Additionally, support for an array of selectors was dropped as well. Update any references to rawCssNamespace with cssNamespace.

If you were already using cssNamespace, update your configuration to use a css selector rather than an array of classes. E.g., cssNamespace: 'moreSpecific' should be cssNamespace: '.moreSpecific' and cssNamespace: ['specific', 'verySpecific'] should be cssNamespace: '.specific .verySpecific'.

The Problem

styled-components is an awesome library for css-in-js and feels like a natural combination of React and CSS. It is easy to use and produces css instead of inline styles.

However, if you are trying to gradually introduce styled-components into a legacy website that might not have the best CSS, the legacy styles may bleed into your styled-components because they have more specificity than the single class styled-components.

The Solution

This plugin will automatically add additional css namespaces or duplicated classes to the selectors produced by styled components effectively creating a wall between the legacy css code and your new shiny styled components.


Styling frameworks

This plugin was built for Styled Components; however, since initially creating it, we at Quick Base have switched to Emotion. It works as an alternative to the stylis extra scope plugin which requires creating your own instance of stylis.


  1. Clone the repo with git clone
  2. yarn install (prefer yarn although npm should work as well)
  3. yarn test to run the tests


When we are ready to release a new version, one of the admins needs to run the following commands to publish the new version to npm. We probably need to invest in a better deploy and semver management system. Interested? See this issue.

  • If needed, open a new PR to update the version in the package.json
  • Copy the commit hash from the commit log
  • Run git tag -a {version} {commit_hash}. For example: git tag -a 0.0.9 abf3123
  • In the editor, add a message about the changes in this version and save
  • Push the tag to GitHub with git push --follow-tags
  • Travis CI will build and publish the new version to npm


Open source software is a group effort. This version of the plugin was heavily inspired by a fork of the original plugin from @TrevorBurnham.

We also would like to thank some of our contributors who helped solve some tough issues with the previous iteration of this plugin:

  • @daniloster
  • @dan-kez
  • @prevostc
  • @danielhusar
You can’t perform that action at this time.