@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.
Display slice zones with custom components.

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	`function` 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. See the table below for available options.

`components` options

Argument	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.	`TODOSliceComponent`

`usePrismic`

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

usePrismic()

`<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.
`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	`function` 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	`string \| function` 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.	`({ isExternal }) => isExternal ? "noreferrer" : undefined`
`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.
`linkResolver` optional	`function` 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"`

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

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"
  :components="components"
/>
```
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"
  :document="aboutUsDocument"
/>
```
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'"
  :rel="({ isExternal }) => isExternal ? 'noreferrer' : undefined"
/>

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"
  :serializer="serializer"
/>
```
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>;

@prismicio/vue - v5

Overview

Install

Register the Vue plugin

Configure your plugin with `createPrismic`

Register the plugin in your Vue app

Access Prismic client and helpers

API

`createPrismic`

`components` options

`usePrismic`

`<PrismicImage>`

`<PrismicLink>`

`<PrismicText>`

`<PrismicRichText>`

`<PrismicEmbed>`

`<SliceZone>`

Upgrading from v4

Install `@prismicio/vue` v5

Provide your own `fetch` polyfill

Replace `htmlSerializer` plugin option

Replace `components.imageComponent` plugin option

Replace `components.linkBlankTargetRelAttribute` plugin option

Replace `<SliceZone>`’s `resolver` prop

Replace `<PrismicImage>`’s `imageComponent` prop

Replace `<PrismicLink>`’s `field` prop when linking documents

Update `<PrismicLink>`’s `rel` attribute behavior

Update `<PrismicLink>`’s `target` attribute behavior

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

Wrap `<PrismicText>` output

Replace `<PrismicRichText>`’s `htmlSerializer` prop

Wrap `<PrismicRichText>` output

Replace `usePrismicImage()`

Replace `usePrismicLink()`

Replace `usePrismicText()`

Replace `usePrismicRichText()`

Replace all query composables

Replace `DefineComponentSliceComponentProps` type