The Gatsby Link API

12/26/2019

One of the easiest to use Gatsby APIs.

Disclaimers

Please make sure you use at least Gatsby V2.1.31 !

This is not a complete guide, I just shed light on features I like the most.

Ux friendly

User experience is the key! I love websites and applications that care about basic ergonomic principles. That’s pretty simple, people stay for the content and the experience.

There are nice APIs you can use to make awesome experiences and supercharge your web application. The Link API is powerful because the difference between a « normal » link and a Gatsby link is huge.

With this API, you will get a very cool instant effect with internal navigation.

Instead of doing this :

export default () => <a href="/contact">Me contacter</a>

which is fine for external links, you’d better use the Link API for your internal links :

import { Link } from "gatsby"

export default () => <Link to={"/contact"}>Me contacter</Link>

No more reload effect, no more blink, no more flash effect.

Gatsby allows for creating PWAs.

The only difference with a classic link is the to attribute instead of href.

Rich API

This API is smart, it takes care of commons needs such as highlighting the current nav menu item in the navigation.

Again, these features are quite easy to use, most of the time you just need to add a simple attribute.

activeStyle et activeClassName

You can use activeStyle and activeClassName to style the current nav menu item.

For example, let’s create the following Menu.js component:

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

export default props => (
  <nav>
    {props.items.map(item => {
      return (
        <Link
          key={item.slug}
          activeClassName="active"
          className="menu-item"
          to={item.url}
        >
          {item.title}
        </Link>
      )
    })}
  </nav>
)

and then in our CSS :

.menu-item.active {
  /* mes styles */
}

You can even pass an object with activeStyle.

Easy way to pass data between pages

Easy money !

With this API, you can pass a state between pages.

Let’s create a ContactLink component :

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

export default() => (
    <Link to={"/contact"} state={ isFromHell: true }>Me contacter</Link>
)

You can use the state like that :

import React from "react"

export default ({ location }) => {
  if (location.state.isFromHell) {
    return <p>Vous revenez de l'enfer !</p>
  } else {
    return <p>Vous avez fait bon chemin.</p>
  }
}

The information is passed from the referer page to the destination.

You can even pass the entire state if you want. This is unlimited :

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

export default({location}) => (
    <Link to={"/contact"} state={ isFromHell: location.state.isFromHell }>Me contacter</Link>
)

Browsing with code

You can use navigate to manually trigger navigation, exactly the same way a user would click on a super-fast Gatsby Link with his mouse.

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

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

      // Implementation of this function is an exercise for the reader.
      const formValues = getFormValues()

      navigate("/form-submitted/", {
        state: { formValues },
      })
    }}
  >
    {/* (skip form inputs for brevity) */}
  </form>
)

Source

NB: it’s just an example, getFormValues() is not defined

This API provides very efficient ways to pass information from one page to another.