Developers / prismic-dom

prismic-dom

Replaced by @prismicio/helpers

prismic-dom is deprecated and replaced by @prismicio/helpers v2. All functions from prismic-dom have been moved into the more general @prismicio/helpers package.

See the @prismicio/helpers v2 Migration Guide to learn how to upgrade your project.

Overview

prismic-dom is one of two fundamental Prismic packages for creating web apps with Prismic and JavaScript. It is primarily responsible for rendering data from the Prismic API as HTML. The other is @prismicio/client, which helps with querying the API.

Dependencies & Requirements

This package works with the Prismic API V2. You can tell if you're using V2 if your endpoint URL includes prismic.io/api/v2.

Installation

  • npm
  • Yarn
npm
Copy
npm install prismic-dom
Yarn
Copy
yarn add prismic-dom

Example

In this example, we will use @prismicio/client to query content from a Prismic repository, and prismic-dom to render the content we receive.

Copy
const PrismicDom = require('prismic-dom')
const Prismic = require('@prismicio/client')

const endpoint = 'https://your-repo-name.cdn.prismic.io/api/v2'
const client = Prismic.client(endpoint)

const init = async () => {
  const { data } = await client.getByUID('page', 'quickstart')
  console.log(PrismicDom.RichText.asHtml(data.description))
  // <p>This <em>should</em> log your formatted text.</p>
}

init()

Usage

This section assumes you have required prismic-dom in your project and stored it in the variable PrismicDom, and that you have a document from the Prismic API stored in the variable document (using @prismicio/client):

Copy
const PrismicDom = require('prismic-dom')

async () => {
  const document = await client.getByUID('page', 'example-document')
  // all operations happen here
}

For the following examples, the document has this structure:

Copy
{
  uid: 'example-document',
  type: 'page',
  // document metadata
  // ...
  data: {
    date: '2018-01-16' // A date field
    link: {...} // An internal link to a blog post with the UID "vacation"
    title: {...} // An h2 title field with the content "This is a Title"
    description: {...} // A block of rich text with formatting
  }
}

prismic-dom offers four methods for rendering HTML:

Date()

PrismicDom.Date() takes a Date field from the Prismic and converts it to an ISO date.

A Date object is a built-in JavaScript object for storing date and time. To learn more about the JavaScript date object, see this tutorial by Tania Rascia.

By default, Prismic dates are formatted: '2020-11-19T16:45:39+0000'.

Copy
PrismicDom.Date(document.data.date)
// 2018-01-16T13:46:15.000Z

PrismicDom.Date(document.data.date).getFullYear()
// 2018

Link.url()

PrismicDom.Link.url() takes a link from the API and a Link Resolver function and returns a URL. (See above for an explanation of Link Resolvers.) Works for Prismic document links, media links, and web links.

Copy
const linkResolver = (document) => {
  if (document.type === 'blog') return "/post/" + document.uid;
  else return "/" + document.uid;
};

PrismicDOM.Link.url(document.data.link, linkResolver)
// /blog/vacation

What is a Link Resolver?

A Link Resolver is a function that formats internal links based on document data. For instance, a document of type "blog_post" with a UID of "vacation" could have the URL path /blog/vacation.

A Link Resolver would look like this:

const linkResolver = (document) => "/" + document.data.uid

That example will return the document's UID as the URL path.

RichText.asText()

PrismicDom.RichText.asText() takes a Rich Text array from the Prismic API and converts it to plain text.

Copy
PrismicDOM.RichText.asText(document.title)
// "This is a Title"

RichText.asHtml()

PrismicDom.RichText.asHtml() takes a Rich Text array from the Prismic API, a Link Resolver function, and an HTML Serializer function, and returns rendered HTML. (See above for an explanation of Link Resolvers.)

Copy
PrismicDom.RichText.asHtml(document.data.description, linkResolver, htmlSerializer)
// <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p><p>Ut enim ad minim veniam.</p>

asHtml() accepts an htmlSerializer function. The function should accept a rich text block (which might be a paragraph, a heading1, etc) and return a converted version of it — such as an HTML representation of it. The function is called for each individual block in the rich text value, and the returned values are joined.

The following code says, "if the type of the element is 'label,' return the text inside strong tags with a class of the label":

Copy
function htmlSerializer(type, element, text, children) {
  if (type === 'label')
    return `<strong class="${element.data.label}">${children.join()}</strong>`
  return null
}

PrismicDom.RichText.asHtml(document.data.description, null, htmlSerializer)
// <strong class="example-class">Example rich text content</strong>

The HTML serializer receives four parameters in the following order: type, element, text, children.

type

string

The type of the element. Example: "span", "heading2", "paragraph", "image".

element

object

A description of the entire element. For inline elements, this includes the start index, end index, type, and — if the element is a custom label — the name of the label. Example:

{
  "start": 0,
  "end": 6, 
  "type": "label", 
  "data": { "label": "codespan" }
}

For block-level elements (eg: paragraph, headings, pre), this includes the type, the text content, and an array containing all of the inline elements. Example:

{
  type: 'paragraph',
  text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.',
  spans: [
    {
      start: 63,
      end: 71,
      type: 'label',
      data: { label: 'codespan' }
    },
  ]
}
text

string

The text of the element. Example:

"Lorem ipsum"

children

array

An array of all child elements, which have already been serialized. Example:

[
  "Massa sapien faucibus ",
  "<strong>cras tincidunt lobortis</strong>",
  ". Pharetra pharetra massa ",
  "<span  class=\"codespan\">ultricies</span>",
  " morbi tincidunt augue interdum."
]

prismic-dom includes a default HTML Serializer to provide standard formatting. To see the default formatting, view the package source code.

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.