Skip to main content

Recipes: Styling with CSS

There are so many ways to add styles to your website; Gatsby supports almost every possible option, through official and community plugins.

Using global CSS files without a Layout component

Prerequisites

  • An existing Gatsby site with an index page component
  • A gatsby-browser.js file

Directions

  1. Create a global CSS file as src/styles/global.css and paste the following into the file:
  1. Import the global CSS file in the gatsby-browser.js file such as the following:

Note: You can also make use of require('./src/styles/global.css') to import the global CSS file in your gatsby-config.js file.

  1. Run gatsby-develop to observe the global styling being applied across your site.

Note: This approach is not the best fit if you are using CSS-in-JS for styling your site, in which case a layout page with all the shared components should be used. This is covered in the next recipe.

Additional resources

Using global styles in a layout component

Prerequisites

Directions

You can add global styles to a shared layout component. This component is used for things that are common throughout the site, like a header or footer.

  1. If you don’t already have one, create a new directory in your site at /src/components.

  2. Inside the components directory, create two files: layout.css and layout.js.

  3. Add the following to layout.css:

  1. Edit layout.js to import the CSS file and output layout markup:
  1. Now edit your site’s homepage at /src/pages/index.js and use the new layout component:

Additional resources

Using Styled Components

Prerequisites

Directions

  1. Inside your gatsby-config.js file add gatsby-plugin-styled-components

  1. Open the index page component (src/pages/index.js) and import the styled-components package

  2. Style components by creating style blocks for each element type

  3. Apply to the page by including styled components in the JSX

  1. Run gatsby develop to see the changes

Additional resources

Using CSS Modules

Prerequisites

Directions

  1. Create a CSS module as src/pages/index.module.css and paste the following into the module:
  1. Import the CSS module as a JSX object style in the index.js file by modifying the page so it looks like the following:
  1. Run gatsby develop to see the changes.

Note: Notice that the file extension is .module.css instead of .css, which tells Gatsby that this is a CSS module.

Additional resources

Using Sass/SCSS

Sass is an extension of CSS that gives you more advanced features like nested rules, variables, mixins, and more.

Sass has 2 syntaxes. The most commonly used syntax is “SCSS”, and is a superset of CSS. That means all valid CSS syntax, is valid SCSS syntax. SCSS files use the extension .scss

Sass will compile .scss and .sass files to .css files for you, so you can write your stylesheets with more advanced features.

Prerequisites

Directions

  1. Install the Gatsby plugin gatsby-plugin-sass and node-sass.

npm install --save node-sass gatsby-plugin-sass

  1. Include the plugin in your gatsby-config.js file.
  1. Write your stylesheets as .sass or .scss files and import them. If you don’t know how to import styles, take a look at Styling with CSS

Note: You can use Sass/SCSS files as modules too, like mentioned in the previous recipe about CSS modules, with the difference that instead of .css the extensions have to be .scss or .sass

Additional resources

Adding a Local Font

Prerequisites

Directions

  1. Copy a font file into your Gatsby project, such as src/fonts/fontname.woff2.
  1. Import the font asset into a CSS file to bundle it into your Gatsby site:

Note: Make sure the font name is referenced from the relevant CSS, e.g.:

By targeting the HTML body element, your font will apply to most text on the page. Additional CSS can target other elements, such as button or textarea.

If fonts are not updating following steps above, make sure to replace the existing font-family in relevant CSS.

Additional resources

Using Emotion

Emotion is a powerful CSS-in-JS library that supports both inline CSS styles and styled components. You can use each styling feature individually or together in the same file.

Prerequisites

Directions

  1. Install the Gatsby Emotion plugin and Emotion packages.
  1. Add the gatsby-plugin-emotion plugin to your gatsby-config.js file:
  1. If you don’t already have one, create a page in your Gatsby site at src/pages/emotion-sample.js.

Import Emotion’s css core package. You can then use the css prop to add Emotion object styles to any element inside a component:

  1. To use Emotion’s styled components, import the package and define them using the styled function.

Additional resources

Using Google Fonts

Hosting your own Google Fonts locally within a project means they won’t have to be fetched over the network when your site loads, increasing your site’s speed index by up to ~300 milliseconds on desktop and 1+ seconds on 3G. It’s also recommended to limit custom font usage to only the essential for performance.

Prerequisites

Directions

  1. Run npm install --save typeface-your-chosen-font, replacing your-chosen-font with the name of the font you want to install from the typefaces project.

An example to load the popular ‘Source Sans Pro’ font would be: npm install --save typeface-source-sans-pro.

  1. Add import "typeface-your-chosen-font" to a layout template, page component, or gatsby-browser.js.
  1. Once it’s imported, you can reference the font name in a CSS stylesheet, CSS Module, or CSS-in-JS.

NOTE: So for the above example, the relevant CSS declaration would be font-family: 'Source Sans Pro';

Additional resources

Edit this page on GitHub
Docs
Tutorials
Plugins
Blog
Showcase