How to Add a Favicon to Your Gatsby Site

Even if you are comfortable with React, moving to Gatsby can present new challenges. Often, this just requires a shift in thinking to “the Gatsby way”, but you may still find yourself stuck on seemingly simple things every now and then. One of these “seemingly simple things” I describe is adding a favicon image to a Gatsby site.

For those who may not have added the finishing touches to a website or have never deployed a website, a favicon is an ICO file of an image that is displayed to the left of the site title in the tab bar in most modern browsers (in some browsers it still appears to the left of the URL in the address bar). Some browsers have the ability to display a 32x32 ICO file as the favicon; however, using a size of 16x16 is common, and some browsers will automatically resize 32x32 to a 16x16 size.

Insert Image of browser favicon

Having a favicon is important for your site because it adds to your overall site’s brand recognition. When a user is browsing the web, they could potentially have 20+ tabs open. When that many tabs are open, the tab widths decrease to fit all the tabs in the width of the browser. This means that the site title will no longer be legible. At that point, the easiest way to recognize a tab (without having to click them all) is to have a unique favicon image. If no favicon is used, the browser will inject it’s default favicon next to your site title.

Heading: Importing a Favicon

If you have an existing Gatsby project, skip ahead of these setup steps and open your project in your favorite code editor. If you do not have Gatsby, you will need node.js and Gatsby installed globally.

To install node.js, click the link for nodejs and follow the instructions for your Operating System:

After that has installed, verify you have it by entering node -v. If you see a version number, you have successfully installed node. All of the following steps involve entering commands into the terminal.

Install Gatsby globally. npm i -g gatsby-cli

After navigating to whichever directory you want to create the new project in, create a new site with the command gatsby new practice-site. The first part of the command gatsby new indicates that you are installing a new Gatsby project. The second part practice site can be named anything you want.

In the terminal, change directories to the project folder cd practice-site

Now that we have completed setup, it’s time to import the favicon. There are a couple options of file types that are widely accepted by browsers, which are PNG and ICO. GIF file types are also partially supported, but not recommended for use at this time. Personally, I stick to the ICO file type because of the backwards compatibility for older browsers. However, if your user base is 99.95% Chrome users, it’s safe to say you can use PNG for your favicon and still be able to sleep soundly at night.

Title: For ICO users (PNG users skip this) If you want to convert your PNG to ICO, this is the time to do it. There are a plethora of free online favicon generators that allow you to drag-and-drop your PNG file into the converter. A couple seconds later, you have a shiny .ico file.

If You Use a Gatsby Starter If you use a Gatsby starter site, the favicon.ico is usually located at either src/images/ or /static/. The newly generated file can be moved into that directory and the old favicon.ico deleted. If the name of the new favicon is not favicon.ico, I prefer to rename it to ‘favicon.ico since there will only be one favicon. You are done, and can type gatsby develop in your terminal, browse to the localhost, and see the favicon changes.

If You Are Using the Gatsby Default If you have a custom project with the default starter, perform the following:

Move the favicon.ico to the /src/images/ directory.

In your code editor, open components/layout.js.

At the top of the file, add the following to the imports:

import favicon from '../images/favicon.ico'
import Helmet from 'react-helmet'

In the Layout function, wrap the entire contents with a <div></div> or a fragment <></>.

Add the following code below the opening div or fragment you just entered

      <link rel="icon" href={favicon} />

Your end result should look similar to this
    import React from "react"
    import PropTypes from "prop-types"
    import { StaticQuery, graphql } from "gatsby"
    import favicon from '../images/favicon.ico'
    import Helmet from 'react-helmet'
    import Header from "./header"
    import "./layout.css"
    const Layout = ({ children }) => (
  <link rel="icon" href={favicon} />
    query SiteTitleQuery {
      site {
        siteMetadata {
  render={data => (
      <Header siteTitle={} />
          margin: `0 auto`,
          maxWidth: 960,
          padding: `0px 1.0875rem 1.45rem`,
          paddingTop: 0,
          © {new Date().getFullYear()}, Built with
          {` `}
          <a href="">Gatsby</a>
    Layout.propTypes = {
      children: PropTypes.node.isRequired,
export default Layout

In the project directory in your terminal, type gatsby develop in your terminal, browse to the localhost, and see the favicon changes.

Congrats, your favicon.ico works!

For PNG Users

Note: If you are using a starter other than the Default Starter from the Gatsby Starter Library, look closely for a favicon.ico in your project. If you have one, it is much less boilerplate to replace the favicon.ico with your new file than convert multiple project files for PNG use.

Move the PNG file into /src/images/.

In your code editor, open gatsby-config.js

Scroll down to gatsby-plugin-manifest and change icon: path to match your new icon filename. Make sure the end format looks like this: src/images/gatsby-icon.png.

In the project directory in your terminal, type gatsby develop in your terminal, browse to the localhost, and see the favicon changes.

Congrats, your favicon.ico works!

Stay tuned for more Gatsby goodness...