@prismicio/vue - v5

Overview

@prismicio/vue is the official Prismic package for creating Vue.js-based websites.

With this package, you can:

Query Prismic content with a dedicated client.
Display Prismic images, links, and rich text using components.
Display slice zones with custom components.

This page documents all APIs provided by @prismicio/vue.

Install

@prismicio/vue is automatically installed when bootstrapping a Nuxt project with @slicemachine/init.

npx @slicemachine/init@latest

It can also be manually installed in any Vue.js project:

npm install --save @prismicio/vue

Register the Vue plugin

@prismicio/vue provides a Vue.js plugin that injects @prismicio/client and Vue components into your project.

Configure your plugin with `createPrismic`

createPrismic configures a Vue.js plugin with your Prismic repository.

prismic.ts

import { createPrismic } from "@prismicio/vue";

const prismic = createPrismic({
  endpoint: "example-prismic-repo",
});

export default prismic;

Register the plugin in your Vue app

The plugin needs to be registered in your Vue app.

main.ts

import { createApp } from "vue";
import App from "./App.vue";
import prismic from "./prismic";

createApp(App).use(prismic).mount("#app");

Access Prismic client and helpers

The plugin injects @prismicio/client’s client and helpers into your Vue app. They can be accessed with usePrismic in your component setup and $prismic in your template sections.

App.vue

<script setup lang="ts">
import { usePrismic } from "@prismicio/vue";

const {
  options,
  client,
  filter,
  cookie,
  // All @prismicio/client helpers are available.
  asText,
  asHTML,
} = usePrismic();
</script>

<template>
  <div>
    {{ $prismic.options }}

    {{ $prismic.client }}
    {{ $prismic.filter }}
    {{ $prismic.cookie }}

    <!-- All @prismicio/client helpers are available. -->
    {{ $prismic.asText }}
    {{ $prismic.asHTML }}
  </div>
</template>

API

`createPrismic`

Creates a Vue.js plugin with your Prismic endpoint and additional options.

createPrismic({
  endpoint: "example-prismic-repo",
});

property

Description

Default

endpoint

string

A Prismic repository name (recommended) or full endpoint.

clientConfig

optional

object

Options for @prismicio/client used to create a client. Only one of clientConfig or client can be used.

client

optional

PrismicClient

An explicit @prismicio/client’s client for the plugin to use directly instead of creating one. Only one of clientConfig or client can be used.

linkResolver

optional

(field: ContentRelationshipField) => string | null | undefined

A link resolver function used to determine a URL from a link field or document. If it returns a value, it takes priority over a route resolver. Prefer using only a route resolver with the plugin’s clientConfig.routes option.

injectComponents

optional

boolean

Whether to inject Prismic components globally into the Vue app.

true

components

optional

object

Options to configure @prismicio/vue’s components.

property

Description

Default

linkRel

optional

string | function

A rel attribute’s value to apply on links rendered by PrismicLink. A function can be provided to use the link’s metadata to determine the rel value.

({isExternal}) => isExternal ? "noreferrer" : undefined

linkInternalComponent

optional

Component | string

A component used by PrismicLink to render internal links.

RouterLink || NuxtLink

linkExternalComponent

optional

Component | string

A component used by PrismicLink to render external links.

"a" || NuxtLink

imageWidthSrcSetDefaults

optional

number[]

Default widths to use when rendering an image with PrismicImage’s widths="defaults" option.

[640, 828, 1200, 2048, 3840]

imagePixelDensitySrcSetDefaults

optional

number[]

Default pixel densities to use when rendering an image with PrismicImage’s pixel-densities="defaults" option.

[1, 2, 3]

richTextComponents

optional

VueRichTextSerializer

A map of rich text block types to Vue components to use with PrismicRichText.

sliceZoneDefaultComponent

optional

Component

Rendered if a component mapping from the SliceZone’s components prop cannot be found.

`usePrismic`

Returns the @prismicio/client’s client and helpers injected by @prismicio/vue.

const prismic = usePrismic();

Components

`<PrismicImage>`

Displays an optimized image from an image field.

<PrismicImage :field="slice.primary.image" />

prop

Description

Default

field

ImageField

An image field to display.

imgixParams

optional

object

An object of imgix URL parameters. See an example.

alt

optional

""

Declare an image as decorative.

fallbackAlt

optional

""

Declare an image as decorative if the image field does not have alt text.

widths

optional

number[] | "thumbnails" | "defaults"

Widths used to build a srcset value for the image field. - "thumbnails" uses the image field’s thumbnails. - "defaults" uses the plugin’s components.imageWidthSrcSetDefaults value. Only one of widths or pixelDensities can be used.

"defaults"

pixelDensities

optional

number[] | "defaults"

Widths used to build a srcset value for the image field. - "defaults" uses the plugin’s components.imagePixelDensitySrcSetDefaults value. Only one of widths or pixelDensities can be used.

`<PrismicLink>`

Displays a link from a link field or a document.

<PrismicLink :field="slice.primary.link" />

prop

Description

Default

field

LinkField

A link field to link. Only one of field or document can be used.

document

PrismicDocument

A Prismic document to link. Only one of field or document can be used.

linkResolver

optional

(field: ContentRelationshipField) => string | null | undefined

A link resolver function used to determine a URL from the field or document prop. If it returns a value, it takes priority over a route resolver. Prefer using only a route resolver with the plugin’s clientConfig.routes option.

rel

optional

undefined | string | ((metadata) => string | undefined)

A rel attribute’s value to apply on the link. A function can be provided to use the link’s metadata to determine the rel value. Use undefined to remove the rel attribute.

"noreferrer" if the link is external.

internalComponent

optional

Component | string

The component used to render internal links.

RouterLink || NuxtLink

externalComponent

optional

Component | string

The component used to render external links.

"a" || NuxtLink

`<PrismicText>`

Displays plain text from a rich text field.

<PrismicText :field="slice.primary.text" />

prop

Description

Default

field

RichTextField

A rich text field to render.

fallback

optional

string

Rendered if the rich text field is empty.

separator

optional

string

Separator used between text blocks.

" "

wrapper

optional

Component | string

An HTML tag name or a component used to wrap the output. The output is not wrapped by default.

`<PrismicRichText>`

Displays formatted text from a rich text field.

<PrismicRichText :field="slice.primary.text" />

prop

Description

Default

field

RichTextField

A rich text field to render.

fallback

optional

Component

Rendered if the rich text field is empty.

components

optional

VueRichTextSerializer

A map of rich text block types to Vue components. See an example.

Standard HTML elements (e.g. heading1 becomes a <h1>).

linkResolver

optional

(field: ContentRelationshipField) => string | null | undefined

A link resolver function used to determine a URL from the field or document prop. If it returns a value, it takes priority over a route resolver. Prefer using a route resolver with the plugin’s clientConfig.routes option instead.

wrapper

optional

Component | string

An HTML tag name or a component used to wrap the output. The output is not wrapped by default.

`<PrismicEmbed>`

Displays HTML from an embed field.

<PrismicEmbed :field="slice.primary.embed" />

prop

Description

Default

field

EmbedField

An embed field to render.

wrapper

optional

Component | string

An HTML tag name or a component used to wrap the output.

"div"

`<PrismicTable>`

Displays a formatted table from a table field.

<PrismicTable :field="slice.primary.my_table_field" />

prop

Description

Default

field

TableField

A table field to render.

fallback

optional

Component

Rendered if the table field is empty.

components

optional

VueTableComponents & VueRichTextSerializer

A map of table elements and and rich text block types to Vue components. The available table elements are table, thead, tbody, tr, th, and td. The available rich text block types are paragraph, em, strong, and hyperlink. See an example.

`<SliceZone>`

Renders slices from a slice zone.

<SliceZone :slices="doc.data.slices" :components="components" />

prop

Description

Default

slices

SliceZone

A slice zone to render.

components

object

A map of slice types to Vue components.

property

Description

Default

slice

Slice

The slice object being displayed.

slices

Slice[]

All slices in the slice zone.

index

number

The index of the slice in the slice zone.

context

unknown

The data passed to SliceZone’s context prop.

defaultComponent

optional

Component

Rendered if a slice does not have a component mapping.

context

optional

any

Arbitrary data made available to all slice components.

wrapper

optional

Component | string

An HTML tag name or a component used to wrap the output. The output is not wrapped by default.

Prop helpers

`getSliceComponentProps`

Returns prop types for a slice component. Components rendered by <SliceZone> should use this helper.

defineProps(getSliceComponentProps());

`getRichTextComponentProps`

Returns prop types for a rich text field block component. Components rendered by <PrismicRichText> should use this helper.

defineProps(getRichTextComponentProps(type));

prop

Description

Default

type

optional

string

The component’s rich text node type.

`getTableComponentProps`

Returns prop types for a table field component. Components rendered by <PrismicText> should use this helper.

defineProps(getTableComponentProps.table());
defineProps(getTableComponentProps.thead());
defineProps(getTableComponentProps.tbody());
defineProps(getTableComponentProps.tr());
defineProps(getTableComponentProps.th());
defineProps(getTableComponentProps.td());

Upgrading from v4

Follow these steps to upgrade an existing project to @prismicio/vue v5.

Install @prismicio/vue v5
@prismicio/vue v5 is automatically installed when using @nuxtjs/prismic v4.
```
npm install --save @prismicio/vue@^5
```
Provide your own fetch polyfill
This step is only necessary if your environment doesn’t provide a browser-compatible fetch implementation. If you’re using Node 18 or later, you can skip this step.
isomorphic-unfetch is no longer provided as a default fetch implementation. If you still need a fetch polyfill, install isomorphic-unfetch:
```
npm install --save isomorphic-unfetch
```
Then, import and configure it with the plugin:
prismic.ts
```
import { createPrismic } from "@prismicio/vue";
import fetch from "isomorphic-unfetch";

const prismic = createPrismic({
  endpoint: "your-repository-name",
  clientConfig: {
    fetch,
  },
});

export default prismic;
```
Replace htmlSerializer plugin option
This step is only necessary if you were using the htmlSerializer plugin option.
Use the richTextSerializer option instead.
prismic.ts
```
import { createPrismic } from "@prismicio/vue";

const prismic = createPrismic({
  endpoint: "your-repository-name",
  htmlSerializer: serializer
  richTextSerializer: serializer
});

export default prismic;
```
The richTextSerializer option is deprecated and will be removed in a future version. Migrate to the new component-based serializer instead with the components.richTextComponents option and the <PrismicRichText>’s components prop.
Replace components.imageComponent plugin option
This step is only necessary if you were using the components.imageComponent plugin option.
Use your own image component instead with @prismicio/client’s helpers.
```
<MyImageComponent
  v-if="$prismic.isFilled(slice.primary.image)"
  :src="$prismic.asImageSrc(slice.primary.image)"
/>
```
Replace components.linkBlankTargetRelAttribute plugin option
This step is only necessary if you were using the components.linkBlankTargetRelAttribute plugin option.
Use the new components.linkRel option.
prismic.ts
```
import { createPrismic } from "@prismicio/vue";

 const prismic = createPrismic({
  endpoint: "your-repository-name",
  components: {
    linkBlankTargetRelAttribute: "noreferrer"
    linkRel: ({ isExternal }) => isExternal ? "noreferrer" : undefined
  }
});
```
When used with @nuxtjs/prismic, the plugin configuration has to be serializable. Instead, export the function from ~/prismic/linkRel.ts for the module to recognize it.
Replace <SliceZone>’s resolver prop
This step is only necessary if you were using <SliceZone>’s resolver prop.
Use the new components prop instead.
```
<SliceZone
  :slices="doc.data.slices"
  :resolver="resolver /* [!code --] */"
  :components="components /* [!code ++] */"
/>
```
Slice Machine generates a components object containing your Vue components for each of your slice libraries.
```
import { components } from "./slices";
```
Replace <PrismicImage>’s imageComponent prop
This step is only necessary if you were using <PrismicImage>’s imageComponent prop.
Use your own image component instead with @prismicio/client’s helpers.
```
<MyImageComponent
  v-if="$prismic.isFilled(slice.primary.image)"
  :src="$prismic.asImageSrc(slice.primary.image)"
/>
```
Replace <PrismicLink>’s field prop when linking documents
This step is only necessary if you were using <PrismicLink>’s field prop with documents.
Use the new document prop instead.
```
<PrismicLink
  :field="aboutUsDocument/* [!code --] */"
  :document="aboutUsDocument/* [!code ++] */"
/>
```
Update <PrismicLink>’s rel attribute behavior
This step is only necessary if you need to preserve the old <PrismicLink>’s rel attribute behavior.
All external links now default to noreferrer. Previously only links with a target="_blank" attribute had a default value.
You can resume the previous behavior globally using the new components.linkRel option.
prismic.ts
```
import { createPrismic } from "@prismicio/vue";

const prismic = createPrismic({
  endpoint: "your-repository-name",
  components: {
    linkRel: ({ isExternal }) => (isExternal ? "noreferrer" : undefined),
  },
});
```
When used with @nuxtjs/prismic, the plugin configuration has to be serializable. Instead, export the function from ~/prismic/linkRel.ts for the module to recognize it.
The function can also be passed directly to <PrismicLink>’s rel prop.
```
<PrismicLink
  :field="slice.primary.link"
  :rel="({ isExternal }) => isExternal ? 'noreferrer' : undefined"
/>
```
noreferrer is equivalent to noopener noreferrer which was the previous default.
Update <PrismicLink>’s target attribute behavior
The target prop is removed. Use the editor to control whether links should be opened in a new tab.

Replace `<PrismicLink>`’s `blankTargetRelAttribute` prop

Use the new rel prop.

<PrismicLink
  :field="slice.primary.image"
  :blankTargetRelAttribute="'noreferrer' /* [!code --] */"
  :rel="({ isExternal }) => isExternal ? 'noreferrer' : undefined /* [!code ++] */"
/>

Wrap <PrismicText> output
This step is only necessary if you need <PrismicText> output to remain wrapped.
<PrismicText> output is no longer wrapped by default. Use the wrapper prop to wrap the output explicitly.
```
<PrismicText
  :field="slice.primary.text"
  wrapper="p"
/>
```
Replace <PrismicRichText>’s htmlSerializer prop
This step is only necessary if you were using <PrismicRichText>’s htmlSerializer prop.
Migrate to the new component-based serializer, or use the (now deprecated) serializer prop during your migration instead.
```
<PrismicRichText
  :field="slice.primary.text"
  :htmlSerializer="serializer /* [!code --] */"
  :serializer="serializer /* [!code ++] */"
/>
```
Wrap <PrismicRichText> output
This step is only necessary if you need <PrismicRichText> output to remain wrapped.
<PrismicRichText> output is no longer wrapped by default. Use the wrapper prop to wrap the output explicitly.
```
<PrismicRichText
  :field="slice.primary.text"
  wrapper="div"
/>
```

Replace `usePrismicImage()`

Use @prismicio/client’s helpers directly.

import { usePrismicImage } from "@prismicio/vue"; 

const image = usePrismicImage(slice.primary.image);

import { computed } from "vue"; 
import { usePrismic } from "@prismicio/vue";

const prismic = usePrismic();

const image = computed(() => {
  return prismic.asImageSrcSet(slice.primary.image);
});

Replace `usePrismicLink()`

Use @prismicio/client’s helpers directly.

import { usePrismicLink } from "@prismicio/vue"; 

const link = usePrismicLink(slice.primary.link);

import { computed } from "vue"; 
import { usePrismic } from "@prismicio/vue";

const prismic = usePrismic();

const link = computed(() => {
  return prismic.asLinkAttrs(slice.primary.link);
});

Replace `usePrismicText()`

Use @prismicio/client’s helpers directly.

import { usePrismicText } from "@prismicio/vue"; 

const text = usePrismicText(slice.primary.text);

import { computed } from "vue"; 
import { usePrismic } from "@prismicio/vue";

const prismic = usePrismic();

const text = computed(() => {
  return prismic.asText(slice.primary.text);
});

Replace `usePrismicRichText()`

Use @prismicio/client’s helpers directly.

import { usePrismicRichText } from "@prismicio/vue"; 

const html = usePrismicRichText(slice.primary.text);

import { computed } from "vue"; 
import { usePrismic } from "@prismicio/vue";

const prismic = usePrismic();

const html = computed(() => {
  return prismic.asHTML(slice.primary.text);
});

Replace all query composables

Use a query library with a Prismic client, such as TanStack Query.

import { usePrismicDocumentByUID } from "@prismicio/vue"; 

const { data } = usePrismicDocumentByUID("page", "home");

import { usePrismic } from "@prismicio/vue"; 
import { useQuery } from "@tanstack/vue-query";

const prismic = usePrismic();

const { data } = useQuery({
  queryKey: ["home"],
  queryFn: () => prismic.client.getByUID("page", "home"),
});

Refer to the following table for each hook’s replacement client method.

Hook	Query method
`usePrismicDocuments()`	`client.get()`
`useFirstPrismicDocument()`	`client.getFirst()`
`useAllPrismicDocumentsDangerously()`	`client.dangerouslyGetAll()`
`usePrismicDocumentByID()`	`client.getByID()`
`usePrismicDocumentsByIDs()`	`client.getByIDs()`
`useAllPrismicDocumentsByIDs()`	`client.getAllByIDs()`
`usePrismicDocumentByUID()`	`client.getByUID()`
`usePrismicDocumentsByUIDs()`	`client.getByUIDs()`
`useAllPrismicDocumentsByUIDs()`	`client.getAllByUIDs()`
`useSinglePrismicDocument()`	`client.getSingle()`
`usePrismicDocumentsByType()`	`client.getByType()`
`useAllPrismicDocumentsByType()`	`client.getAllByType()`
`usePrismicDocumentsByTag()`	`client.getByTag()`
`useAllPrismicDocumentsByTag()`	`client.getAllByTag()`
`usePrismicDocumentsBySomeTags()`	`client.getBySomeTags()`
`useAllPrismicDocumentsBySomeTags()`	`client.getAllBySomeTags()`
`usePrismicDocumentsByEveryTag()`	`client.getByEveryTag()`
`useAllPrismicDocumentsByEveryTag()`	`client.getAllByEveryTag()`

Replace `DefineComponentSliceComponentProps` type

Use the return type of getSliceComponentProps instead.

import { getSliceComponentProps } from "@prismicio/vue";

type DefineComponentSliceComponentProps = ReturnType<
  typeof getSliceComponentProps
>;