Configure the Link and Content Relationship Fields

This article explains what the Links and Content Relationship fields are and how to configure them in the Custom Type builder.


The Link and Content Relationship fields are used to add links to the web, documents in your Prismic repository, or files in your Prismic Media Library.

Links vs Content Relationships

There are three kinds of links in Prismic:

  • Link to an external URL (Can also be used for mailto and tel links)
  • Link to another document in the current Prismic repository.
  • Link to a file in your media library (e.g. a PDF, image, or audio file)

By default, the Link field will allow an author to select any of these options.

To restrict the field to link to documents within the repository, use the Content Relationship field.

To restrict the field only to select a media item, use the Link to Media field.

Content Relationship configuration

Screenshot of the Content relationship field in the drag-and-drop editor.

The Content Relationship field links to another document in your Prismic repository. It allows you to set constraints based on Custom Type and Tag when an author is selecting a document.

The visual builder

You'll see constraint options when configuring a Content Relationship field, as well as the Field name, API ID, and Field placeholder. These options allow you to set the constraints basing on specific Custom Types and Tags.

Screenshot of the Content Relationship field editor.

JSON model

The following table displays the JSON configuration options available in the JSON editor.

type

string (required)

Value must be Link

config

object

Object for the configuration options

config.label

string

The label that shows up for the field in the entry editor

config.placeholder

string

A user-friendly placeholder for the field in the entry editor

config.select

string

Must be "document"

config.customtypes

array

Filters the document list by the specified custom types

config.tags

array

Filters the document list by the specified tags

Example JSON configuration

The following JSON defines a Content Relationship field with both Custom Type and Tag constraints:

Copy
"example_content_relationship": {
  "type": "Link",
  "config": {
    "select": "document",
    "customtypes": [
      "article"
    ],
    "tags": [
      "Featured"
    ],
    "label": "Related Article",
    "placeholder": "Select a Related Article..."
  }
}

API response example

Here is an API response example of a Content Relationship field with the API ID of example_content_relationship:

Copy
// API response example of a Content Relationship field

{
  // ...
  "example_content_relationship":{
    "id":"XxnD3REAACYAk_CJ",
    "type":"page",
    "tags":["…"],
    "slug":"vaporwave",
    "lang":"en",
    "uid":"unique_uid",
    "link_type":"Document",
    "isBroken":false
  }
}

Link and Link to Media configuration

The Link field is used to add links to the web, documents in your Prismic repository without constraints, or files in your Prismic media library.

Screenshot of the Link field in the drag-and-drop editor.

The Link to Media field is used for adding a link to a file in your Prismic media library. It is a specific configuration of the Link field.

Screenshot of the Link to media field in the drag-and-drop editor.

The visual builder

You'll see options to set the Field name, API ID, and Field placeholder for both fields. The only difference will be that the Link field allows you to select a checkbox to Allow target blank.

Screenshot of the Link field editor.

JSON model

The following table explains all the configuration options of Link fields in the JSON editor:

type

string (required)

Value must be Link

config

object

Object for the configuration options

config.label

string

The label that shows up for the field in the entry editor

config.placeholder

string

A user-friendly placeholder for the field in the entry editor

config.select

string

If set to web, it restricts the link to only select a Link to the web

config.allowTargetBlank

boolean

If set to true, will allow an author to select the Open in a new tab option

Example JSON configuration

The following JSON defines a link to anything (external URL, internal content, or media library file):

Copy
"example_link": {
  "type": "Link",
  "config": {
    "label": "Link to Anything",
    "placeholder": "Link to anything..."
  }
}

API response example

Here is an API response example of a Link field with the API ID of example_link:

Copy
// API response example of a Link field

{
  //...
  "example_link":{
    "link_type":"Web",
    "url":"https://prismicio.io"
  }
}

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.