Template Content

On this page, you'll learn how to template content from the Prismic API in your Svelte application.

Intro to templating

Content from Prismic comes in different types. Some are simple fields, like numbers or booleans. Others are structured fields, like titles, rich text, and links.

Simple field types can be injected directly into your application:

<span>{document.data.example_number}</span>
<!-- <span>74</span> -->

@prismicio/svelte includes components for rendering structured fields. To render rich text, for instance, you can use <PrismicRichText>:

<PrismicRichText field={document.data.example_title} />

To get started, let’s look at the structure of the API response.

The structure of the API response

When you use Prismic’s query methods, you will see three different types of API responses:

paginated responses, which return a response object
get-all responses, which return a results array
get-single responses, which return a document object

In fact, these are all part of the same structure: the response object contains the results array, in which each item is a document object.

Here’s more detail about what that each looks like:

The `response` object

When you make a query using a paginated get method, like get(), you will get a response object, which contains pagination information and an array of up to 100 API results. Here is a truncated example of an API response containing some simple fields:

{
  "page": 1,
  // Metadata for this query
  // ...
  "results": [
    {
      "uid": "example_document",
      // Metadata for this result
      // ...
      "data": {
        "example_date": "2020-12-10",
        "example_timestamp": "2020-12-10T04:05:09+0000",
        "example_color": "#c7ab5d",
        "example_number": 74,
        "example_key_text": "Example Key Text Value",
        "example_select": "North",
        "example_boolean": true
      }
    }
    // Other documents...
  ]
}

If you store the response in a variable called response you might access a single data point like this:

response.results[0].data.example_key_text;
// Example Key Text Value

In Svelte, you might use that like this:

<h3>{response.results[0].data.example_key_text}</h3>
<!-- <h3>Example Key Text Value</h3> -->

Or, you might loop over the results array and template each item, like this:

<ul>
  {#each response.results as document}
    <li>{document.data.example_key_text}</li>
  {/each}
</ul>

The most important property on the response object is the results array.

The `results` array

When you make a query using a get-all method, such as getAllByType(), you will get a results array containing all matching results. (If you use a paginated get method, it will contain a results array with up to 100 documents.)

Here is a truncated example of an API response using getAllByType():

[
  {
    "uid": "example_blog_post",
    "type": "blog_post",
    "data": {
      "example_date": "2020-12-10",
      "example_key_text": "Example Key Text Value"
    }
  }
  // Other documents...
]

If you store the response in a variable called results you might access a single data point like this:

results[0].data.example_key_text;
// Example Key Text Value

In Svelte, you might use that like this:

<h3>{results[0].data.example_key_text}</h3>
<!-- <h3>Example Key Text Value</h3> -->

The results array is an array of document objects.

The `document` object

The helper functions getSingle(), getByUID(), and getByID() will return a document object, which contains the data for an individual document directly.

Here’s a truncated example of the response for those queries:

{
  "uid": "about",
  // Metadata for this result
  // ...
  "data": {
    "example_date": "2020-12-10",
    "example_color": "#c7ab5d",
    "example_key_text": "Example Key Text Value"
  }
}

With a single document query, you might access your data like this:

<h3>{document.data.example_key_text}</h3>
<!-- <h3>Example Key Text Value</h3> -->

Simple fields

The content for each Prismic field is delivered as either a simple primitive value or an object. The simple fields can be injected directly into your app since their value is either a string, a number, or a boolean. Here are the simple fields:

Color
Key text
Number
Select
Boolean
Date
Timestamp

Here’s an example of how to use the number field. You can template the other simple fields similarly.

<span>{document.data.example_number}</span>
<!-- <span>74</span> -->

Retrieving the color field is similar. Here we can see how to do inline styling in Svelte:

<h3 style="color: {document.data.example_color};">
  My favorite color is Red
</h3>
<!-- <h3 style="color: #FF00000;">My favorite color is Red</h3> -->

Date and timestamp

The date and timestamp fields from Prismic are strings. The raw response for each of these fields has the following formats:

Date: YYYY-MM-DD
Timestamp: YYYY-MM-DDTHH:MM:SS+0000

@prismicio/client provides an asDate() function to convert a date or timestamp field from Prismic into a JavaScript date object. This is helpful if you need to format the field value into something more user-friendly.

Geopoint

The geopoint field is served as an object with two properties: latitude and longitude. This is the API response:

{
  "example_geopoint": {
    "latitude": 48.85392410000001,
    "longitude": 2.2913515000000073
  }
}

Here is an example of how to retrieve the latitude and longitude coordinates for a geopoint field.

<p>
  My location is
  {document.data.example_geopoint.latitude.toFixed(2)},
  {document.data.example_geopoint.longitude.toFixed(2)}
</p>

<!-- <p>My location is 48.85, 2.29</p> -->

Embed

This is the API response of the embed field:

"example_embed": {
  "version": "1.0",
  "url": "https://prismic.io",
  "type": "link",
  "title": "Make your website editable for the whole team - Prismic",
  "provider_name": null,
  "thumbnail_url": "https://images.prismic.io/prismic-website/6e49007fec52f99861047cdd55b3ab190ea04295_dev-landing-page-image.png?auto=compress,format",
  "html": "<div data-type=\"unknown\"><a href=\"https://prismic.io\"><h1>Make your website editable for the whole team - Prismic</h1></div>",
  "embed_url": "https://prismic.io/"
}

You can template an embed field using <PrismicEmbed>.

<script>
  import { PrismicEmbed } from "@prismicio/svelte";
</script>

<PrismicEmbed field={document.data.example_embed} />

<PrismicEmbed> outputs an <iframe> element. The <iframe> may have a default height and width defined by the oEmbed provider. You can style the iframe’s height and width using Svelte’s :global() CSS modifier.

The following example will scale the <iframe> to 100% width.

<div class="parent">
  <PrismicEmbed field={document.data.example_embed} />
</div>

<style>
  .parent :global(iframe) {
    /* Style all iframes that are descendants of .parent */
    width: 100%;
    height: auto;
  }
</style>

Images

The image field returns an object with data about the image, including a URL for your image (hosted on Prismic’s servers) and alt text.

{
  "example_image": {
    "dimensions": {
      "width": 1920,
      "height": 1302
    },
    "alt": "Pink flowers on a tree",
    "copyright": null,
    "url": "https://images.prismic.io/sm-20201204-2/7d1fba99-5bec-4d59-b8eb-402706e2d36c_a-pril-62u95KgB49w-unsplash.jpg?auto=compress,format"
  }
}

You can template an image using @prismicio/svelte’s <PrismicImage> component. It renders an optimized image using Prismic’s built-in image optimization.

<script>
  import { PrismicImage } from "@prismicio/svelte";
</script>

<PrismicImage field={document.data.example_image} />

Prismic delivers images through the imgix API, which means you can leverage the power of imgix to apply optimizations and transformations. Prismic automatically formats, compresses, and sizes your images. Transformations allow you to resize, crop, recolor, and more. See Imgix’s URL API Reference for a full list of transformations.

You can change these settings or apply new transformations with the imgixParams prop.

The following example converts the image to grayscale with sat: -100:

<script>
  import { PrismicImage } from "@prismicio/svelte";
</script>

<PrismicImage
  field={document.data.example_image}
  imgixParams={{ sat: -100 }}
/>

We recommend using <PrismicImage> for most cases. However, you can also use the following helpers from @prismicio/client to template images: asImageSrc(), asImageWidthSrcSet(), and asImagePixelDensitySrcSet().

For more information on <PrismicImage>, see the @prismicio/svelte Technical Reference.

Rich text and titles

Rich text and titles are delivered in an array that contains information about the text structure. Here’s an example of the API response of the rich text field (title fields follow the same format).

{
  "example_rich_text": [
    {
      "type": "paragraph",
      "text": "Example Rich Text Value",
      "spans": [
        {
          "start": 8,
          "end": 17,
          "type": "strong"
        }
      ]
    }
  ]
}

Output with formatting

To render rich text and title fields, use the <PrismicRichText> component. It will convert your rich text field to Svelte components.

<script>
  import { PrismicRichText } from "@prismicio/svelte";
</script>

<PrismicRichText field={document.data.example_rich_text} />

Creating a rich text serializer

To modify the HTML output of a rich text field, create a rich text serializer function. The rich text serializer identifies an element by its type and returns output accordingly. Here is an example of a rich text serializer that will return a user-defined <Title> component for heading1 elements.

<script>
  import { PrismicRichText } from "@prismicio/svelte";
  import Title from "../components/Title.svelte";
  export let data;

  const richTextSerializer = {
    heading1: () => Title,
  };
</script>

<PrismicRichText
  field={data.exampleDocument.data.example_rich_text}
  components={richTextSerializer}
/>

The <Title> component will receive the content of the element in a slot.

Learn more about customizing rich text output in Rich Text.

Output without formatting

The <PrismicText> component will convert and output the text in the rich text or title field as a string.

<script>
  import { PrismicText } from "@prismicio/svelte";
</script>

<PrismicText field={document.data.example_rich_text} />

Links and content relationships

The link field allows you to link to an external webpage, an internal Prismic document, or an item in your Media Library (like a PDF). The content relationship field allows you to link specifically to an internal Prismic document.

Here’s what a content relationship field looks like from the API (a link field takes a similar format). This field has an API ID example_content_relationship, and it links to another document that has the UID another-document and the type page.

{
  "example_content_relationship": {
    "id": "X9C65hEAAEFIAuLo",
    "type": "page",
    "tags": [],
    "slug": "another-document",
    "lang": "en-us",
    "uid": "another-document",
    "link_type": "Document",
    "isBroken": false,
    "text": "Click Here"
  }
}

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 document

Link to web

Here’s how to render a link from a link to web.

<script>
  import { PrismicLink } from "@prismicio/svelte";
</script>

<!-- With default text property -->
<PrismicLink field={document.data.example_link} />;

<!-- Overriding with custom children -->
<PrismicLink field={document.data.example_link}>
  Example Link
</PrismicLink>

The target and rel attributes will be set automatically if the link field is set to open the link in a new window.

Pull in data from another document

To pull in content from another content, you must fetch that content in your API Query, using the graphQuery or fetchLinks option. To use fetchLinks, the value should be:

First, the API ID of the custom type is referenced in your content relationship field.
Then, the API ID of the field that you want to retrieve.

If you have a custom type called blog that includes a content relationship field called example_content_relationship linked to a custom type called author where you want to retrieve a field that has an API ID is author_name:

<script>
  const document = await client.getByUID(
    "blog",
    "my-blog-post",
    { fetchLinks: "author.author_name" },
  );
</script>

Once you have adjusted your API query, the linked content will appear in a data object nested in the link or content relationship field:

{
  "example_content_relationship": {
    "id": "X9C65hEAAEFIAuLo",
    "type": "blog",
    "tags": [],
    "slug": "another-page-title",
    "lang": "en-us",
    "uid": "my-blog",
    "data": {
      "author_name": "John Doe"
    },
    "link_type": "Document",
    "isBroken": false
  }
}

You can then template that content:

<strong
  >By {document.data.example_content_relationship.data
    .author_name}</strong
>
<!-- <strong>By John Doe</strong> -->

Groups

A group field renders an array of content fields. Here’s what the API response looks like for a hypothetical group field modeling a nav menu.

{
  "example_group": [
    {
      "example_nav_label": "Homepage",
      "example_nav_link": {
        // Link object...
      }
    },
    {
      "example_nav_label": "About",
      "example_nav_link": {
        // Link object...
      }
    }
  ]
}

To template a group fields, use an #each block like this:

<script>
  import { PrismicLink } from "@prismicio/svelte";
</script>

<ul>
  {#each document.data.example_group as item}
    <li>
      <PrismicLink field={item.example_nav_link}>
        {item.example_nav_label}
      </PrismicLink>
    </li>
  {/each}
</ul>

Slices

Slices are repeatable, rearrangeable content sections. Learn more about slices in What is a Slice?

On the document object, slices are stored in the slices array, like so:

{
  "slices": [
    {
      "slice_type": "text_slice",
      "slice_label": null,
      "items": [{}],
      "primary": {
        "rich_text": [
          {
            "type": "paragraph",
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
            "spans": []
          }
        ]
      }
    },
    {
      "slice_type": "image_gallery_slice",
      "slice_label": null,
      "items": [
        // Item objects...
      ],
      "primary": {
        "gallery_title": [
          {
            "type": "heading1",
            "text": "Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "spans": []
          }
        ]
      }
    }
  ]
}

To render slices, use the <SliceZone> component from @prismicio/svelte by passing an array of slices from the API and a list of Svelte components for each type of slice. In the following example, the components are imported from a library of slices exported from the src/lib/slices/index.js file.

+page.svelte

<script>
  import { SliceZone } from "@prismicio/svelte";

  import { components } from "$lib/slices";

  /** @type {import('./$types').PageData} */
  export let data;
</script>

<SliceZone slices={data.page.data.slices} {components} />

Each slice component will receive the following props that can be used to display the slice’s content.

slice: The slice object being rendered
index: The index of the slice within the slices array
slices: The list of all slice objects in the slices array
context: Arbitrary data passed to the <SliceZone>’s context prop

A simple slice component could look like this:

<script>
  import { PrismicRichText } from "@prismicio/svelte";

  /** @type {import("@prismicio/client").Content.TextSlice} */
  export let slice;
</script>

<section>
  <PrismicRichText field={slice.primary.text} />
</section>