Developers / Field

What Is a Field?

In this article, you'll learn what fields are and how to use them in your custom types.

Fields are the most elementary unit of content of a Prismic custom type model. You use fields, along with Slices, to create your custom types. Each field is designed to hold different data types to cover all use cases.

Prismic has eighteen different field types.

Eight of those fields are simple fields that return a simple value in the API, like a number (3) or a color ("#f3f3f3"):

  • UID
  • Boolean
  • Color
  • Date
  • Timestamp
  • Number
  • Key text

The other ten fields are structured fields that return a structured JSON object in the API:

  • Title
  • Rich text
  • Image
  • Content relationship
  • Link
  • Link to media
  • Embed
  • Geopoint
  • Group
  • Integration

Edit JSON models with caution

Only edit JSON models to make changes to the rich text field labels or set a min or max value for a number field. Making abrupt changes can cause conflicts when synchronizing changes with your documents.

UID

The UID field is a unique identifier used to create SEO-friendly website URLs. These are the characteristics of the UID field:

  • The value is unique to the custom type and locale.
  • It is space-free and written in lowercase, such as about-us. Spaces are replaced with dashes.
  • It can't contain special characters (except hyphens and underscores).
  • The Prismic development kits provide special helper functions for querying by UID.
  • When a UID is changed, the old value is permanently saved, so documents can always be queries by old UIDs. (This prevents links on your website from breaking.)

Edit UIDs

To learn more about how to create and edit UIDs, see Edit a Document's Unique Identifier.

The following table displays the JSON keys and values of the field’s API response.

type

string (required)

Must be UID

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

Here is an API response example of a UID field:

Copy
// API response example of a UID field

{
 //...
 "uid": "unique-value"
}

Boolean

The boolean field allows content writers to select a “true” or “false” value. When you add this field in a custom type, it'll be available as a toggle in the document.

When you add a new boolean field with a default value to a custom type with existing documents, these existing documents will not be automatically updated with the default value. You'll need to re-publish them for the new value to take effect.

type

string (required)

The value must be boolean

config

object

Object for the configuration options

config.label

string

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

config.placeholder_false

string

A user-friendly placeholder for the field's false value

config.placeholder_true

string

A user-friendly placeholder for the field's true value

config.default_value

string

Selecting this option will default the value to be true

Here is an API response example of a boolean field with the API ID of example_boolean:

Copy
// API response example of a boolean field

{
 //...
 "example_boolean": true
}

Color

The color field allows content writers to select a color through a variety of color pickers and have the option to input a hex color value manually.

type

string (required)

Value must be Color

config

object

Object for the configuration options

config.label

string

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

Here is an API response example of a color field with the API ID of example_color:

Copy
// API response example of a color field

{
  //...
  "example_color": "#5b295f"
}

Date

The date field allows content writers to add a date that represents a calendar day. This field is different from the timestamp field, which includes both a date and a time.

type

string (required)

Value must be Date

config

object

Object for the configuration options

config.label

string

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

config.default

string

If set to now, it will automatically fill with today's date.

The default value will only apply to newly created documents. When you set or change the default value, it will not change existing documents.

Here is an API response example of a date field with the API ID of example_date:

Copy
// API response example of a date field

{
 //...
 "example_date": "2022-10-22"
}

Timestamp

The timestamp field allows content writers to add a specific date and time. This field is different from the date field, which does not include a time of day.

type

string (required)

Value must be Timestamp

config

object

Object for the configuration options

config.placeholder

string

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

config.label

string

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

config.default

string

If set to now, it will automatically fill with today's date and the current time. The default value will only apply to newly created documents. When you set or change the default value, it will not change existing documents.

Here is an API response example of a timestamp field with the API ID of example_timestamp:

Copy
// API response example of a timestamp field

{
 //...
 "example_timestamp":"2020-06-27T05:00:00+0000"
}

Number

The number field allows content writers to add a numeric entry. You can set maximum and minimum values if needed.

type

string (required)

Value must be Number

config

object

Object for the configuration options

config.placeholder

string

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

config.label

string

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

config.min

integer

The minimum allowable value for the number

config.max

integer

The maximum allowable value for the number

min and max can only be configured in the JSON editor.

Here is an API response example of a number field with the API ID of example_number:

Copy
// API response example of a number field

{
  //...
  "example_number": 12
}

Key Text

The key text field allows content writers to enter a text string, it does not output any HTML. This makes it different from the rich text field, which outputs formatted text.

type

string (required)

Value must be text

config

object

Object for the configuration options

config.placeholder

string

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

config.label

string

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

Here is an API response example of a key text field with the API ID of example_key_text:

Copy
// API response example of a key text field

{
  //...
  "example_key_text": "Lorem Ipsum",
}

Select

The select field allows content writers to pick among a number of options from a dropdown menu.

type

string (required)

Value must be select

config

object

Object for the configuration options

config.label

string

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

config.placeholder

string

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

config.options

array

An array of strings that will be the available options in the select dropdown

config.default_value

string

If it's set to the be first value in the options, the select will default to this option

Here is an API response of a select field with the API ID of example_select:

Copy
// API response example of a select field

{
  //...
  "example_select": "My selected Value"
}

Title

The title field is a configurable field dedicated to titles and headings.

type

string (required)

Value must be StructuredText

config

object

Object for the configuration options

config.placeholder

string

Defines a user-friendly placeholder

config.label

string

Defines the label that shows up for the field in the editor

config.labels

array

An array of strings to define labels for custom formatting

config.single

string

A comma-separated list of formatting options

Options: heading1 | heading2 | heading3 | heading4 | heading5 | heading6

The following JSON defines a single heading title field:

Copy
// API response example of a title field
{
  //...
  "example_title":[
    {
      "type":"heading1",
      "text":"Lorem ipsum",
      "spans":[]
    }
  ]
}

Rich Text

The rich text field allows content writers to edit rich content with standard formatting options, such as bold, italics, headings, and lists. Want to learn more about rich text? See the rich text article.

If the 'Allow multiple paragraphs' option is unchecked in the visual builder, then "multi" will change to "single" in the JSON editor.

If neither "multi" nor "single" are specified in the config object, then the field will allow multiple paragraphs and include all the available formatting options.

type

string (required)

The value must be StructuredText

config

object

Object for the configuration options

config.placeholder

string

Defines a user-friendly placeholder

config.label

string

Defines the label that shows up for the field in the editor

config.labels

array

An array of strings to define labels for custom formatting

config.multi

string

A comma-separated list of formatting options, with paragraph breaks allowed
Options: paragraph | preformatted | heading1 | heading2 | heading3 | heading4 | heading5 | heading6 | strong | em | hyperlink | image | embed | list-item | o-list-item | rtl

config.single

string

A comma-separated list of formatting options that does not allow line breaks

Options: paragraph | preformatted | heading1 | heading2 | heading3 | heading4 | heading5 | heading6 | strong | em | hyperlink | image | embed | list-item | o-list-item | rtl

config.imageConstraint

object

Set the width and/or height constraints of any image added to the field. The object has two properties: width and height, with integers as their values, representing the image size in pixels.

Here is an API response example of a rich text field with the API ID of example_rich_text:

Copy
// API response example of a rich text field
{
  //...
  "example_rich_text": {
    "type": "StructuredText",
    "config": {
      "single": "paragraph",
      "label": "Rich Content",
      "placeholder": "Rich Content",
      "labels": [
        "right-align",
        "center-align"
      ]
    }
  }
}

Image

The image field allows content writers to upload an image with variable size constraints, which developers can use for responsive layouts. Want to learn more about the image field? See the image field reference.

type

string (required)

Value must be Image

config

object

Object for the configuration options

config.label

string

Sets 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.constraint

object

The width and height constraints for the image

config.constraint.width

integer

An integer will define the width of the image in pixels. If you set as null, there will be no constraint

config.constraint.height

integer

An integer will define the height of the image in pixels. If you set as null, there will be no constraint

config.thumbnails

array

Define the responsive image views for the image. For each view, give an object with a name, width, and height

config.thumbnails.name

string

The name for the image view

config.thumbnails.width

integer

An integer that defines the width of the image view in pixels

config.thumbnails.height

integer

An integer that defines the height of the image view in pixels

Below you can see an example API response of an image field with the API ID of example_image that has a mobile responsive view:

Copy
// API response example of an image field

{
  // ...
  "example_image":{
    "dimensions":{
      "width":2048,
      "height":1536
    },
    "alt":null,
    "copyright":null,
    "url":"https://images.prismic.io/slicemachine-blank/dcea6535-f43b-49a7-8623-bf281aaf1cb2_roller-skating.png?auto=compress,format"
  },
  "mobile":{
    "dimensions":{
      "width":500,
      "height":500
    },
    "alt":null,
    "copyright":null,
    "url":"https://images.prismic.io/slicemachine-blank/dcea6535-f43b-49a7-8623-bf281aaf1cb2_roller-skating.png?auto=compress,format&rect=255,0,1536,1536&w=500&h=500"
  }
}

Content Relationship

The content relationship field allows you to create taxonomies, nested menus, and complex data structures. Content relationships allow you to link between documents internally and retrieve data. Want to learn more about the content relationship field? See the content relationship article.

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

Here is an API response example of a content relationship field:

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

Link

The link field creates web links. The link field and the content relationship field look similar. The link field should be used to create web links, like a CTA. The content relationship should be used to create data structures, such as a tagging system or nested nav menu.

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.

If set to media, it restricts the link to only select a link to a media item.

If set to document, it restricts the link to only select a link to a document.

config.allowTargetBlank

boolean

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

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"
  }
}

Link to media

The link to media field allows you to upload files. The link field and link to media fields look similar. The link field should be used to create web links, like a CTA. The link to media field should be used to host files.

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

Must be "media"

config.allowTargetBlank

boolean

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

Here is an API response example of a link to media field:

Copy
"example_link_to_media": {
  "link_type": "Media",
  "name": "mona-lisa",
  "kind": "image",
   "url": "https://images.prismic.io/example-prismic-repo/mona-lisa?auto=compress,format",
  "size": "50",
  "height": "500",
  "width": "800"
},

Embed

The embed field allows you to add a valid oEmbed URL, like YouTube, Vimeo, or Soundcloud.

type

string (required)

Value must be Embed

config

object

Object for the configuration options

config.label

string

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

config.placeholder

string

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

Here is an API response example of an embed field with the API ID of example_embed:

Copy
// API response example of an embed field

{
  // ...
  "example_embed":{
    "height":113,
    "width":200,
    "embed_url":"https://www.youtube.com/watch?v=GtuLg6hcV3w",
    "type":"video",
    "version":"1.0",
    "title":"Prismic — Basics",
    "author_name":"Prismic",
    "author_url":"https://www.youtube.com/channel/UCJq6AEgtWeZt7ziQ-fLKOeA",
    "provider_name":"YouTube",
    "provider_url":"https://www.youtube.com/",
    "cache_age":null,
    "thumbnail_url":"https://i.ytimg.com/vi/GtuLg6hcV3w/hqdefault.jpg",
    "thumbnail_width":480,
    "thumbnail_height":360,
    "html":"<iframe width=\"200\" height=\"113\" src=\"https://www.youtube.com/embed/GtuLg6hcV3w?feature=oembed\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen></iframe>"
  }
}

Geopoint

The geopoint field allows you to add geolocation coordinates or a Google Maps URL.

type

string (required)

Value must be GeoPoint

config

object

Object for the configuration options

config.label

string

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

Here is an API response of a geopoint field with the API ID of example_geopoint:

Copy
// API response example of a geopoint field

{
 //...
 "example_geopoint": {
    "latitude": 20.632784250388028,
    "longitude": 0.0019419193267822268
  }
}

Group

The group field is used to create a repeatable collection of fields. You can use the group field to create an image gallery, a banner, a list of products, a navigation list, and more.

A group field cannot be put inside a Slice or another group field

It is not possible to nest groups. You cannot put a group field inside a group field, nor can you put a group field inside a Slice.

type

string (required)

Value must be Group

config

object

Object for the configuration options

config.fields

object (required)

Defines the fields in the group with their optional configuration. Set up each field as described in their respective references.

config.label

string

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

config.repeat

boolean

If set to false, it configures the group as not repeatable.

Below you can see the API response example of a group field with the API ID of example_group with a key text and a number field:

Copy
// API response example of a group field

{
  // ...
  "example_group":[
    {
      "key_text_description":"Lorem",
      "number_price":55
    },
    {
      "key_text_description":"Ipsum",
      "number_price":60
    }
  ]
}

Integration

The integration field lets you integrate data from an external API with your content. After setting up an integration field in Settings, the next step will be to add the field to your custom type.

To use an integration field, you must first set up an integration field API in your repository settings. Want to learn how to set up an integration field? See Set up an integration field.

type

string (required)

The value must be IntegrationFields

config

object (required)

Object for the configuration options

config.catalog

string

A label that indicates the catalog you're going to use. It must contain your repo name and the name of the catalog, separated by dashes, for example your-repo-name—name-of-your-integration

config.label

string

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

config.placeholder

string

A user-friendly placeholder into the field

Below you can see an example of an integration field's API response:

Copy
// API response example of an integration field

{
 // ...
  "example_integration_field":{
    "id":6562914664611,
    "title":"Organic coffee blend",
    "body_html":"",
    "vendor":"Bare Blends",
    "product_type":"coffee blend",
    "created_at":"2021-03-08T15:46:19+11:00",
    "handle":"organic-toast-golden",
    "updated_at":"2021-04-07T10:31:07+10:00",
    "published_at":null,
    "template_suffix":"",
    "published_scope":"web",
    "tags":"",
    "admin_graphql_api_id":"gid://shopify/Product/6562914664611",
    "variants":["…"],
    "options":["…"],
    "images":["…"],
    "image":{"…"}
  }
}
Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.