Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 36 ยท Pages and Routing

Styling in Gatsby

Style a Gatsby site with global CSS, CSS Modules, Sass, CSS-in-JS and Tailwind. Learn how scoping works, where to import styles and how to avoid unstyled flashes.

Gatsby does not force a styling approach. Plain CSS, CSS Modules, Sass, CSS-in-JS libraries and Tailwind all work, and most are enabled by installing a plugin or a package. Your choice mostly affects scoping (will my .title rule leak into other components?) and where the CSS ends up in the built site. This lesson compares the common options, shows how each is set up and demonstrates scoping with a runnable stand-in.

Gatsby code is read-only; the stand-ins and HTML demo are runnable.

Global CSS

Create a stylesheet and import it once in gatsby-browser.js:

CSS
/* src/styles/global.css */
:root { --accent: #6b3fa0; }
body { font-family: system-ui, sans-serif; margin: 0; line-height: 1.6; }
a { color: var(--accent); }
JavaScript
// gatsby-browser.js (real Gatsby, read-only)
import "./src/styles/global.css"

Global CSS is perfect for resets, fonts, CSS variables and base element styles. Its risk is that every rule applies everywhere. Importing the file also in a layout component works, and Gatsby extracts it into a .css file in the build so no JavaScript is needed to style the first paint.

CSS Modules

A file named something.module.css is scoped to the component that imports it. Gatsby 5 uses named exports by default:

CSS
/* src/components/card.module.css */
.card { border: 1px solid #ddd; border-radius: 8px; padding: 1rem; }
.title { margin: 0 0 .5rem; }
JSX
// src/components/card.js (real Gatsby, read-only)
import * as React from "react"
import * as styles from "./card.module.css"

const Card = ({ title, children }) => (
  <article className={styles.card}>
    <h3 className={styles.title}>{title}</h3>
    {children}
  </article>
)
export default Card

At build time .card becomes something like card-module--card--3x9Fa, a unique name, so another component can define its own .card without a clash. Write class names in camelCase (.cardTitle) so you can use styles.cardTitle; names with dashes need bracket access: styles["card-title"].

If you migrate from Gatsby 4, remember the change: v4 used import styles from, v5 uses import * as styles from.

Sass

Install sass and the Sass plugin:

Terminal
npm install sass gatsby-plugin-sass
JavaScript
// gatsby-config.js (real Gatsby, read-only)
module.exports = { plugins: ["gatsby-plugin-sass"] }

Now .scss and .module.scss files work, with variables, nesting and mixins.

CSS-in-JS and Tailwind

  • styled-components and Emotion need their Gatsby plugins (gatsby-plugin-styled-components, @emotion/babel-preset-css-prop) so server-rendered HTML contains the styles. Without that, the page flashes unstyled.
  • Tailwind CSS is installed with PostCSS: add tailwindcss and a postcss.config.js, import the Tailwind directives in a global CSS file and list your component paths in tailwind.config.js content. The generator npm init gatsby can set this up for you.

Rule of thumb: prefer solutions that output static CSS files (global CSS, modules, Sass, Tailwind). They are fastest. Runtime CSS-in-JS adds JavaScript work in the browser.

flowchart LR
  A["global.css"] --> X["extracted .css file"]
  B["card.module.css"] --> X
  C["Sass"] --> X
  D["Tailwind"] --> X
  X --> P["public/"]

All the static options end up as plain CSS files in the build.

Stand-in: how CSS Modules scope class names

This stand-in is not the real CSS Modules loader, but it shows the principle: rename each class with a unique prefix and give the component a map from the short name to the unique name.

JS Stand-in: scoping class names

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A live demo of scoping in plain HTML

A browser can show why unscoped styles collide. Both rules below use the class .title; the second one overrides the first for both headings, which is exactly the problem scoping prevents.

The collision that modules prevent

Both headings turn blue. With CSS Modules each component would own its own .title and the red heading would stay red.

Avoiding a flash of unstyled content

  • Import global CSS in gatsby-browser.js (or a layout) so it is part of the build, not loaded later.
  • For CSS-in-JS, install the SSR plugin and check gatsby build && gatsby serve, not just the dev server.
  • Put critical fonts in <link rel="preload"> from the Head API (pages) and set font-display: swap.

Use CSS variables for colors and spacing in your global stylesheet. They work in every approach above and make dark mode and theming simple.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where should a global stylesheet usually be imported?

    gatsby-browser.js (or the layout) imports it once so it applies to the whole site.
  2. 2. How does Gatsby 5 expect CSS Modules to be imported?

    Gatsby 5 uses named exports, so you import the namespace.
  3. 3. What do CSS Modules do to the class .title?

    The loader renames classes to unique names, so components cannot collide.
  4. 4. Why do CSS-in-JS libraries need Gatsby plugins?

    Without SSR support, the styles appear only after JavaScript runs, causing a flash of unstyled content.

Summary

  • Global CSS suits resets, fonts and variables; import it in gatsby-browser.js.
  • *.module.css files are scoped per component; Gatsby 5 imports them with import * as styles.
  • Sass and Tailwind need small setup; CSS-in-JS needs SSR plugins.
  • Static CSS options are the fastest because they ship as plain .css files.
  • Always check styling in a production build to catch unstyled flashes.

Next: GraphQL Basics in Gatsby