Templating Links

🕙 Before Reading

This article assumes that you have queried your API and saved the document object in a variable named document.

If this isn't the case, learn how to Retrieve the response here.

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.

Here's an example response from the API from these fields (all three links take the same format):

Copy
query MyQuery {
  allPrismicPost {
    edges {
      node {
        data {
          example_content_relationship_or_link {
            id
            isBroken
            lang
            link_type
            raw
            size
            slug
            tags
            target
            type
            uid
            url
            document {
              ... on PrismicExampleType {
                data {
                  example_title {
                    raw
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

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, these can be either internal links to documents or external links.

Internal links

When using internal links, you'll use Gatsby Link to be able to link between pages. The routes will be automatically built by the plugin and provided to you in the url value of your link, so you'll need to pass the url value of the Gatsby <Link />.

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

const linkToInternalDoc = (doc) => {
  const linkedDoc = doc.example_content_relationship
  return (
    <div>
      <Link id={linkedDoc.id} to={linkedDoc.url}>Link to a doc</Link>
    </div>
  )
}

export default linkToInternalDoc

⚠️ Only use Gatsby Link for internal links

This component is intended only for links to pages handled by Gatsby. For links to pages on other domains or pages on the same domain not handled by the current Gatsby site, use the normal <a> element.

External links

For these types of links, you can use the Link utility from prismic-reactjs. Give it a Link to the web or to a media file and you'll get a full-fledged URL:

Copy
import React from 'react'
import { Link as PrismicLink } from 'prismic-reactjs'

const ExternalLink = (doc) => {
  const link = doc.example_link
  return (
    <div>
      <a href=(PrismicLink.url(link.url))>
         Link to the web
      </a>
    </div>
  )
}

export default ExternalLink

Pull in content from another Prismic document

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

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

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

export default linkToDoc

ℹ️ Is your 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 link path. Read Templating Rich Text fields to learn how.