What Is a Field?

Learn what fields are and how to use them in your custom types.

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
Repeatable group
Integration

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.)

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:

// 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:

// 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:

// 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:

// 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:

// 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

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

// 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:

// 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:

// 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:

// 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.

`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:

// API response example of a rich text field

{
  // ...
  "example_rich_text": [
    {
      "type": "paragraph",
      "text": "Est incidunt quis eaque quos. Praesentium alias quia nulla velit est. Dolor consectetur qui porro.",
      "spans": []
    }
  ]
  // ...
}

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:

// 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",
    "id": "ZZ0naHt8YpyOwHlT"
  },
  "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",
    "id": "ZZ0naHt8YpyOwHlT"
  }
}

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:

{
  // ...
  "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
`config.allowText` boolean	If set to true, will allow an author to add display text
`config.repeat` boolean	If set to true, will allow editors to create lists of links

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

// API response example of a non-repeatable Link field

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

// API response example of a repeatable Link field

{
  //...
  "example_links": [
    {
      "link_type": "Web",
      "url": "https://prismicio.io",
      "text": "Visit Prismic!",
    },
    {
      "link_type": "Web",
      "url": "https://prismicio.io/docs",
      "text": "View the Prismic docs",
    }
  ]
}

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
`config.allowText` boolean	If set to true, will allow the author to add a display text to the link

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

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

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:

// 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-nocookie.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:

// API response example of a geopoint field

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

Repeatable group

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

`type` string (required)	Value must be Group
`config` object	Object for the configuration options
`config.fields` object (required)	Defines the fields in the repeatable 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 repeatable group field with the API ID of example_group with a key text and a number field:

// API response example of a repeatable 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.

`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:

// 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":{"…"}
  }
}