How to use styled components in Gatsby

How to use styled components in Gatsby

Composing custom useStaticQuery hooks

ByMario Kandut

honey pot logo

Europe’s developer-focused job platform

Let companies apply to you

Developer-focused, salary and tech stack upfront.

Just one profile, no job applications!

When starting a new Gatsby project, there are several options for styling available, SCSS/SASS, CSS-in-JS, inline-css, good-old plain CSS, CSS frameworks like Bootstrap, Bulma, Tailwind or ...! styled-components is one of the most popular CSS-in-JSS solutions out there, and behold, I have good news, It works flawlessly with Gatsby.

I assume you already have a working Gatsby project running and are looking how to implement styled-components in Gatsby.


💰 The Pragmatic Programmer: journey to mastery. 💰 One of the best books in software development, sold over 200,000 times.

Installing styled-components is an easy two-step process.

1. Install the dependencies

The first step is to install the needed dependencies:

  • styled-components: The main styled-components framework. It was build for React and can automatically handle SSR, automatic vendor prefixing, easy-deletion of CSS, dynamic styling, etc. (see styled-components docs).
  • gatsby-plugin-styled-components: The official Gatsby.js plugin for styled components. Otherwise, the styled-components won't be rendered, when you build your site.
  • babel-plugin-styled-components: This plugin adds support for server-side rendering, minification of styles, and a nicer debugging experience.
npm i styled-components gatsby-plugin-styled-components babel-plugin-styled-components

2. Add the plugin to your Gatsby config

The second and final step is adding the plugin into the Gatsby configuration gatsby-config.js.

// if you want to change the default options
  resolve: `gatsby-plugin-styled-components`,
  options: {
    // ssr: false
    // displayName: false,
    // minify: false
    // see docs

// If you don't want to change defaults


styled-components utilises tagged template literals to style your components. It removes the mapping between components and styles.

This basically means that when you're defining your styles, you're actually creating a normal React component, that has your styles attached to it.

Basic example

This basic example writes Hello World in white on a black background. Look at the components in the render.

const Title = styled.h1`
  font-size: 2em;
  text-align: center;
  color: white;

const Wrapper = styled.section`
  padding: 2em;
  background: black;
// render styled components
    <Title>Hello World!</Title>

Adapt based on props

You can adapt the styles based on props. In the example below, the color of the button changes based on the primary prop.

const Button = styled.button`
  /* Adapt based on primary prop */
  background: ${props => (props.primary ? 'black' : 'white')};
  color: ${props => (props.primary ? 'white' : 'black')};

  font-size: 1em;
  margin: 1em;
  padding: 0.25em 1em;
  border: 2px solid palevioletred;
  border-radius: 3px;

    <Button primary>Primary</Button>

Extending Styles

You can also extend existing styles in your component.

const Button = styled.button`
  color: black;
  font-size: 1em;
  margin: 1em;
  padding: 0.25em 1em;
  border: 2px solid black;
  border-radius: 3px;

// A new component based on Button, but with some styles override
const RedButton = styled(Button)`
  color: red;
  border-color: red;

    <Button>Normal Button</Button>
    <RedButton>Red Button</RedButton>

YaY, 🥳🥳🥳. Well done. You know the basics of styled-components and Gatsby.

For more examples, check out the official docs from styled-components here.

Thanks for reading and if you have any questions, use the comment function or send me a message @mariokandut.

References (and Big thanks): styled-components, Daniel

Scroll to top ↑