Template Links

On this page, you'll learn how to template Link fields in your Gatsby application.


šŸ•™ Before reading

This page assumes that you have saved the response of your queries in a variable named document and that you've already installed theĀ prismic-reactjsĀ library. You'll use this library to import helper components into your templates, as shown below:

import { Link, RichText } from 'prismic-reactjs'

Types of links

There are a few different types of links in Prismic:

  • The Link to Media acts similarly to the Link field, only that this one is dedicated to internal Prismic media files.
  • The Link field allows you to link to an external website, an item in your Media Library (like a PDF), or an internal Prismic document, similar to a Content Relationship field.
  • The Content Relationship field allows you to link specifically to an internal Prismic document.

The response from a Link field will variate depending on the needs of your use case. Here are truncated example responses from these fields:

  • Content Relationship
  • Link
  • Link to media
Copy
{
 // truncated example response
  "example_content_relationship": {
    "document": {
      "url": "/about",
      "type": "page"
    },
    "link_type": "Document"
  },
}
Copy
{
 // truncated example response
  "example_link": {
    "url": "https://google.com",
    "link_type": "Web"
  },
}
Copy
{
 // truncated example response
  "example_link_to_media": {
    "url": "https://images.prismic.io/slicemachine-blank/dcea6535-f43b-49a7-8623-bf281aaf1cb2_roller-skating.png?auto=compress,format",
    "link_type": "Media"
  },
}

There are two things that you might want to do with a link:

  • Link to another page or media item, internally or externally
  • Pull in content from another Prismic document

Here's how to do those two things:

Link to another page or media item

You have two options depending on the type of link you're rendering, and these can be either internal links to documents or external links.

Internal links

Use Gatsby Link to create links between pages. The routes will be automatically built by the plugin and provided to you in the URL field from the queries to pass them to the Gatsby <Link />.

In the following example, we create a linkToInternalDoc component that renders a link to internal documents:

Copy
import * as React from 'react'
import { Link } from 'gatsby'

export const ExternalLink = (document) => {
  const link = document.data.example_link
  return <Link to={link.url}>Link to a doc</Link>
}

External links

For these types of links, use anchor tags. Use the url field from Link to the web or a media file from the queries, and you'll get a full-fledged URL.

In the following example, we create an ExternalLink component that renders a link to external routes using an anchor tag:

Copy
import * as React from 'react'

export const ExternalLink = (document) => {
  const link = document.data.example_link
  return <a href={link.url}>Link to the web</a>
}

Pull content from a linked document

To access the data from a linked document, access the document.data node from the linked doc retrieved from the query. In the next example, we render a linked document's Title field that has the API ID of example_title:

Copy
import * as React from 'react'
import { RichText } from 'prismic-reactjs'

export const linkedDocTitle = (document) => {
  const linkedDoc = document.data.example_content_relationship
  return (
    <div>
      <RichText render={linkedDoc.document.data.example_title.raw} />
    </div>
  )
}

Link inside a Rich Text field

If the link to a document you're using is inside a Rich Text field, you'll need a Link Resolver to determine the internal navigation.

Here's an example of a Custom Link component that you can reuse in your project. Read Templating Rich Text fields to learn how to use it in your Rich Text fields:

Copy
import * as React from 'react'
import { Link } from 'gatsby'
import { linkResolver } from './path-to-LinkResolver'

export const CustomLink = (type, element, content, children, index) => {
  if (element.data.link_type === 'Document') {
    <Link to={linkResolver(element.data)} key={element.data.id}>
      {content}
    </Link>
  }

  if (element.data.link_type === 'Web') {
    <a id={element.data.id} href={element.data.url}>
      {content}
    </a>
  }
  return null
}

Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.