Skip to main content

Creating global styles

In nearly every site, there will be some global styles, such as a reset or typography defaults. This guide will walk through how to add global styles to your site, whether you use standard .css files (or with preprocessors like Sass/Less) or a CSS-in-JS solution.

Table of Contents

How to add global styles in Gatsby with standard CSS files

The best way to add global styles is with a shared layout component. This layout component is used for things that are shared throughout the site, including styles, header components, and other common items.

NOTE: This pattern is implemented by default in the default starter.

To create a shared layout with global styles, start by creating a new Gatsby site with the hello world starter.

# Create the site
gatsby new global-styles https://github.com/gatsbyjs/gatsby-starter-hello-world

Open your new site in your code editor and create a new directory at /src/components. Inside, create two new files:

  global-styles/
  └───src/
      └───components/
+     │   │─  layout.js
+     │   └─  layout.css
      │
      └───pages/
          └─  index.js

Inside src/components/layout.css, add some global styles:

src/components/layout.css
div {
  background: red;
  color: white;
}

In src/components/layout.js, include the stylesheet and export a layout component:

src/components/layout.js
import React from "react"
import "./layout.css"

export default ({ children }) => <div>{children}</div>

Finally, update src/pages/index.js to use the new layout component:

src/pages/index.js
import React from "react"
import Layout from "../components/layout"

export default () => <Layout>Hello world!</Layout>

Run gatsby develop and you’ll see the global styles applied.

Global styles

How to add global styles in Gatsby using CSS-in-JS

NOTE: For this example, we’ll be using Emotion, but the implementation is similar for other CSS-in-JS solutions as well.

To start, create a new Gatsby site with the hello world starter and install gatsby-plugin-emotion and its dependencies:

# Create the site
gatsby new global-styles https://github.com/gatsbyjs/gatsby-starter-hello-world

npm install --save gatsby-plugin-emotion emotion emotion-server react-emotion

Create gatsby-config.js and add the Emotion plugin:

gatsby-config.js
module.exports = {
  plugins: [`gatsby-plugin-emotion`],
}

Next, add a layout component at src/components/layout.js:

src/components/layout.js
import React from "react"
import styled from "react-emotion"
import { injectGlobal } from "emotion"

injectGlobal`
  div {
    background: red;
    color: white;
  }
`

const Wrapper = styled("div")`
  border: 2px solid green;
  padding: 10px;
`

export default ({ children }) => <Wrapper>{children}</Wrapper>

Then, update src/pages/index.js to use the layout:

src/pages/index.js
import React from "react"
import Layout from "../components/layout"

export default () => <Layout>Hello world!</Layout>

Run gatsby build, and you can see in public/index.html that the styles have been inlined globally.

Add global styles with CSS files and no layout component

In some cases, using a shared layout component is not desirable. In these cases, you can include a global stylesheet using gatsby-browser.js.

NOTE: This approach does not work with CSS-in-JS. Use shared components to share styles in CSS-in-JS.

First, open a new terminal window and run the following commands to create a new default Gatsby site and start the development server:

gatsby new global-style-tutorial https://github.com/gatsbyjs/gatsby-starter-default
gatsby develop

Second, create a css file and define any styles you wish. An arbitrary example:

src/styles/global.css
html {
  background-color: lavenderblush;
}

a {
  color: rebeccapurple;
}

Then, include the stylesheet in your site’s gatsby-browser.js file.

NOTE: This solution works when including css as those styles are extracted when building the JavaScript but not for css-in-js. Including styles in a layout component or a global-styles.js is your best bet for that.

gatsby-browser.js
import "./src/styles/global.css"

// or:
// require('./src/styles/global.css')

Note: You can use Node.js require or import syntax. Additionally, the placement of the example css file in a src/styles folder is arbitrary.

You should see your global styles taking effect across your site:

Global styles example site


Was this helpful? edit this page on GitHub