The Gatsby Link API

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

CMS contents

Gatsby works great with CMS. It grabs contents from any external API so it’s quite easy to set up a Gatsby app that fetches contents from a CMS like WordPress.

But in WordPress links within post content are absolute URLs. Don’t worry, you can use a Gatsby plugin to automatically convert those links into Gatsby Links. Use Gatsby catch links for that.

Transition yikes!

I don’t think transition effects are that useful. Most of the time, it just increases the load time.

Please be cautious with it. From what I saw, there are a lot of unwanted side effects and bugs.

Wrap up

When using Gatsby it’s better to use the Link API for your internal links. It’s fast and smooth. No need to ruin everything with super complex transition effects unless you want to create a completely new experience but it’s kinda risky.

The classic links (a tags) must be used for external links.

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