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-browser.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 sass.

npm install 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.

  2. 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

This example shows how to set up the Open Sans font. If you have a different Google Font you want to use, you can find the corresponding package in NPM or the packages directory in the Fontsource repository.

  1. Run npm install @fontsource/open-sans to download the necessary package files.

  2. Then within your app entry file or site component, import the font package. It is recommended you import it via the layout template (layout.js). However, importing via page component (index.js), or gatsby-browser.js are viable alternatives.

If you wish to select a particular weight or style, you may specify it by changing the import path.

Note: The range of supported weights and styles a font may support is shown in each package’s README file.

  1. Once it’s imported, you can reference the font name in a CSS stylesheet, CSS Module, or CSS-in-JS.

Additional resources

Using Font Awesome

Using Font Awesome gives you access to thousands of icons for use on your site. Since Gatsby sites are React sites, it’s recommended to use the react-fontawesome SVG library.

Prerequisites

Directions

  1. Install the react-fontawesome dependencies.

Note that there are multiple icon libraries within react-fontawesome. You may also be interested in free-regular-svg-icons and free-solid-svg-icons which you would install the same way.

  1. Import the FontAwesomeIcon component and the icon you want to use. Then use the icon as a component directly in your JSX files:

This example imports a single, specific icon and uses it for improved performance. As an alternative, you can import the icons and build a library.

Additional resources

Edit this page on GitHub