<Link /> Usage

You should use the <Link /> component as a replacement for HTML <a> tags that represent links between pages in the same Gatsby site. However, you should still use HTML <a> tags for all links that reference pages that are external to Gatsby, as seen in the following example:

import React from "react"
import { Link } from "gatsby"

const Page = () => (
  <div>
    <p>
      Check out my <Link to="/blog">blog</Link>!
    </p>
    <p>
      {/* Note that external links still use `a` tags. */}
      Follow me on <a href="https://twitter.com/gatsbyjs">Twitter</a>!
    </p>
  </div>
)

Active Styles for <Link />

To apply an active state to a Gatsby <Link /> component that indicates it is representative of the page the user is currently viewing, you can use one of two props:

• activeStyle, which is a style object that will only be applied when the current link item is active

• activeClassName, which is a class name that will only be added when the current item is active

This is illustrated in the following example:

import React from "react"
import { Link } from "gatsby"

const SiteNavigation = () => (
  <nav>
    <Link
      to="/"
      {/* This assumes the `active` class is defined in your CSS */}
      activeClassName="active"
    >
      Home
    </Link>
    <Link
      to="/about/"
      activeStyle={{ color: "red" }}
    >
      About
    </Link>
  </nav>
)

Sometimes, you may need to indicate a <Link /> as active even if its path only partially matches the current URL. By default, the activeStyle and activeClassName props will only be set on a given <Link /> component if there is an exact match between the path and the current URL. However, you may need to represent multilevel or other menus where, say, a <Link /> component pointing to /blog also needs to be active for /blog/lorem-ipsum.

In this case, use the partiallyActive prop to indicate that a partial match rather than an exact match should use the given activeStyle or activeClassName prop. This is illustrated in the following example:

import React from "react"
import { Link } from "gatsby"

const Header = <>
  <Link
    to="/articles/"
    activeStyle={{ color: "red" }}
    partiallyActive={true}
  >
    Articles
  </Link>
</>;

Working with Props in <Link />

There are three ways that Gatsby allows you to work with props in the context of the <Link /> component:

• The getProps prop is useful for advanced styling.

• The state prop allows you to pass state as props to the linked page.

• The replace prop allows you to modify the Back button’s behavior.

The getProps prop can be used on any <Link /> component and will yield an object that contains the following properties:

• isCurrent, which is set to true if the location.pathname is identical to the <Link /> component’s to prop value

• isPartiallyCurrent, which is set to true if the location.pathname begins with the <Link /> component’s to prop value

• href, which is the value of the to prop

• location, which represents the page’s location object

The state prop is used when you wish to pass data from the source page to the destination page of a <Link /> component. This is done by passing a state prop to the <Link /> component, or during an invocation of the navigate helper function. The destination page will have a location prop containing a nested state object whose structure represents the passed data.

Consult the following example from the Gatsby documentation:

const PhotoFeedItem = ({ id }) => (
  <div>
    <Link
      to={`/photos/${id}`}
      state={{ fromFeed: true }}
    >
      View Photo
    </Link>
  </div>
)

const Photo = ({ location, photoId }) => {
  if (location.state.fromFeed) {
    return <FromFeedPhoto id={photoId} />
  } else {
    return <Photo id={photoId} />
  }
}

The replace prop is used to modify the Back button’s behavior. In one of the most common cases, you can use it to ensure that the current page, which may be a page you do not want the user to be able to navigate back to using the Back button (such as a confirmation page), is not saved in the browser history. You can use the replace prop to substitute the current page’s URL in the browser history with the destination of the <Link />, as seen in the following example:

import React from "react"
import { Link } from "gatsby"

const AreYouSureLink = () => (
  <Link
    to="/confirmation/"
    replace
  >
    Yes, I’m sure
  </Link>
)

navigate

In many situations, you need to enforce navigation to pages programmatically, by navigating to a different page on the user’s behalf. In these cases, instead of the <Link /> component, you need the navigate helper function.

To conduct programmatic navigation, Gatsby provides a navigate helper function as an export that accepts to and options arguments, as seen in Table B-1.

The navigate function operates the same way as a clicked <Link /> component by default in Gatsby.

The following example demonstrates the use of the navigate function with a state prop:

import React from "react"
import { navigate } from "gatsby"

const Form = () => (
  <form
    onSubmit={event => {
      event.preventDefault()

      const formValues = getFormValues()

      navigate(
        "/form-submitted/",
        {
          state: { formValues },
        }
      )
    }}
  >
    {/* Form input elements */}
  </form>
)

And this example demonstrates the use of the navigate function with a replace prop:

import React from "react"
import { navigate } from "gatsby"

const Form = () => (
  <form
    onSubmit={event => {
      event.preventDefault()

      navigate(
        "/form-submitted/",
        { replace: true }
      )
    }}
  >
    {/* Form input elements */}
  </form>
)

StaticImage

The StaticImage component can take all the image options described in “Image Options” as props, as well as all the shared props listed in Table B-2. It also takes one additional required prop, listed in Table B-3.

The images are loaded and processed at build time, so there are restrictions on how you pass props to the component. The values need to be statically analyzed at build time, which means you can’t pass them as props from outside the component, or use the results of function calls, for example. You can either use static values, or use variables within the component’s local scope:

export function Dino() {
  // Local variables are fine
  const width = 300
  return <StaticImage src="trex.png" width={width} />
}

If you find yourself wishing you could use a prop for the image src, then it’s likely that you should be using a dynamic image:

// A variable in the same file is fine
const width = 300
export function Dino() {
  // This works because the value can be statically analyzed
  const height = (width * 16) / 9
  return <StaticImage src="trex.png" width={width} height={height} />
}

GatsbyImage

This component accepts all the shared props listed in Table B-2, as well as the one in Table B-4. These props are passed directly to the component, and are not to be confused with image options, which are passed to the GraphQL resolver when using dynamic images.

Image Options

There are a few differences in how you specify options for StaticImage and GatsbyImage:

• When using StaticImage, options are passed as props to the component, whereas for the GatsbyImage component they are passed to the gatsbyImageData GraphQL resolver.

• In the StaticImage component, props such as layout and placeholder take a string, while the resolver takes a GraphQL enum, which is uppercase by convention and is not quoted like a string. Both syntaxes are shown in the following table.

Table B-5 lists the options available to both static and dynamic images. We’ll look at these in more detail in the following sections.

<StaticImage
  src="./dino.png"
  alt="A dinosaur"
  layout="fixed"
/>

dino {
  childImageSharp {
    gatsbyImageData(layout: FIXED)
  }
}

Helper Functions

There are a number of utility functions to help you work with gatsbyImageData objects. Gatsby strongly recommends that you do not try to access the internals of these objects directly, as the format could change; instead, use the functions described in the following sections.

import { getImage } from "gatsby-plugin-image"

const image = getImage(data.avatar)
// This is the same as:
const image = data?.avatar?.childImageSharp?.gatsbyImageData

import { getSrc } from "gatsby-plugin-image"

// ...
const src = getSrc(data.hero)
return <meta property="og:image" content={src} />

import { GatsbyImage, getImage, withArtDirection } from "gatsby-plugin-image"

export function MyImage({ data }) {
  const images = withArtDirection(getImage(data.largeImage), [
    {
      media: "(max-width: 1024px)",
      image: getImage(data.smallImage),
    },
  ])

  return <GatsbyImage image={images} />
}