--- title: "@prismicio/vue - v5" tags: ["latest"] category: "api-references" audience: developers lastUpdated: "2025-12-09T03:11:18.000Z" --- # Overview `@prismicio/vue` is the official Prismic package for creating [Vue.js](https://vuejs.org)-based websites. With this package, you can: * Query Prismic content with a dedicated client. * Display Prismic [images](https://prismic.io/docs/fields/image.md), [links](https://prismic.io/docs/fields/link.md), and [rich text](https://prismic.io/docs/fields/rich-text.md) using components. * Display [slice zones](https://prismic.io/docs/slice.md) with custom components. This page documents all APIs provided by `@prismicio/vue`. > See the [Nuxt guide](https://prismic.io/docs/nuxt.md) to learn how to build websites using this package. > **Important** > > We only guarantee support with Nuxt websites. # Install `@prismicio/vue` is automatically installed when [bootstrapping](https://prismic.io/docs/nuxt.md#set-up-a-nuxt-website) a [Nuxt](https://nuxt.com) project with `@slicemachine/init`. ```sh npx @slicemachine/init@latest ``` It can also be manually installed in any Vue.js project: ```sh npm install --save @prismicio/vue ``` # Register the Vue plugin `@prismicio/vue` provides a [Vue.js plugin](https://vuejs.org/guide/reusability/plugins) that injects [`@prismicio/client`](https://prismic.io/docs/technical-reference/prismicio-client.md) and Vue components into your project. > The plugin is automatically registered in Nuxt projects using [`@nuxtjs/prismic`](https://prismic.io/docs/technical-reference/nuxtjs-prismic/v4.md). 1. **Configure your plugin with `createPrismic`** `createPrismic` configures a Vue.js plugin with your Prismic repository. ```ts filename=prismic.ts import { createPrismic } from "@prismicio/vue"; const prismic = createPrismic({ endpoint: "example-prismic-repo", }); export default prismic; ``` 2. **Register the plugin in your Vue app** The plugin needs to be registered in your Vue app. ```ts filename=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`](https://prismic.io/docs/technical-reference/prismicio-client.md)'s client and helpers into your Vue app. They can be accessed with `usePrismic` in your component [setup](https://vuejs.org/api/composition-api-setup.html#composition-api-setup) and `$prismic` in your template sections. > `usePrismic` is automatically imported in Nuxt projects using [`@nuxtjs/prismic`](https://prismic.io/docs/technical-reference/nuxtjs-prismic/v4.md). ```vue filename=App.vue ``` # API ## `createPrismic` Creates a [Vue.js plugin](https://vuejs.org/guide/reusability/plugins) with your Prismic endpoint and additional options. ```ts createPrismic({ endpoint: "example-prismic-repo", }); ``` | Property | Type | Description | Default | | --------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | endpoint | string | A Prismic repository name (recommended) or full endpoint. | None | | clientConfig (optional) | object | Options for [`@prismicio/client`](https://prismic.io/docs/technical-reference/prismicio-client.md) used to create a client. Only one of `clientConfig` or `client` can be used. | None | | client (optional) | PrismicClient | An explicit [`@prismicio/client`](https://prismic.io/docs/technical-reference/prismicio-client.md)'s client for the plugin to use directly instead of creating one. Only one of `clientConfig` or `client` can be used. | None | | linkResolver (optional) | (field: ContentRelationshipField) => string \| null \| undefined | A [link resolver](https://prismic.io/docs/route-resolver.md#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](https://prismic.io/docs/route-resolver.md). Prefer using only a [route resolver](https://prismic.io/docs/route-resolver.md) with the plugin's `clientConfig.routes` option. | None | | injectComponents (optional) | boolean | Whether to inject Prismic components globally into the Vue app. | `true` | | components (optional) | object (see definition below) | Options to configure `@prismicio/vue`'s components. | `({isExternal}) => isExternal ? "noreferrer" : undefined` | **Child properties:** | Property | Type | 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`. | None | | sliceZoneDefaultComponent (optional) | Component | Rendered if a component mapping from the `SliceZone`'s `components` prop cannot be found. | None | ## `usePrismic` Returns the [`@prismicio/client`](https://prismic.io/docs/technical-reference/prismicio-client.md)'s client and helpers injected by `@prismicio/vue`. ```ts const prismic = usePrismic(); ``` # Components ## `` Displays an optimized image from an [image field](https://prismic.io/docs/fields/image.md). ```vue-html ``` > See examples and tips on the [image field](https://prismic.io/docs/fields/image.md#display-images) page. | Prop | Type | Description | Default | | ------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | | field | ImageField | An image field to display. | None | | imgixParams (optional) | object | An object of [imgix URL parameters](https://docs.imgix.com/apis/rendering). See an [example](https://prismic.io/docs/fields/image.md#transform-images-through-the-api). | None | | alt (optional) | "" | Declare an image as decorative. | None | | fallbackAlt (optional) | "" | Declare an image as decorative if the image field does not have alt text. | None | | 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. | None | ## `` Displays a link from a [link field](https://prismic.io/docs/fields/link.md) or a document. ```vue-html ``` > See examples and tips on the [link field](https://prismic.io/docs/fields/link.md#display-links) page. | Prop | Type | Description | Default | | ---------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | field | LinkField | A link field to link. Only one of `field` or `document` can be used. | None | | document | PrismicDocument | A Prismic document to link. Only one of `field` or `document` can be used. | None | | linkResolver (optional) | (field: ContentRelationshipField) => string \| null \| undefined | A [link resolver](https://prismic.io/docs/route-resolver.md#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](https://prismic.io/docs/route-resolver.md). Prefer using only a [route resolver](https://prismic.io/docs/route-resolver.md) with the plugin's `clientConfig.routes` option. | None | | 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` | ## `` Displays plain text from a [rich text field](https://prismic.io/docs/rich-text.md). ```vue-html ``` | Prop | Type | Description | Default | | ------------------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | field | RichTextField | A rich text field to render. | None | | fallback (optional) | string | Rendered if the rich text field is empty. | None | | separator (optional) | string | Separator used between text blocks. | `" "` | | wrapper (optional, deprecated) | Component \| string | An HTML tag name or a component used to wrap the output. The output is not wrapped by default. Prefer wrapping the component with an HTML element instead. | None | ## `` Displays formatted text from a [rich text field](https://prismic.io/docs/rich-text.md). ```vue-html ``` > See examples and tips on the [rich text field](https://prismic.io/docs/fields/rich-text.md#display-rich-text) page. | Prop | Type | Description | Default | | ------------------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | field | RichTextField | A rich text field to render. | None | | fallback (optional) | Component | Rendered if the rich text field is empty. | None | | components (optional) | VueRichTextSerializer | A map of rich text block types to Vue components. The available heading types are `heading1` to `heading6`. The available block types are `paragraph`, `preformatted`, `list`, `oList`, `listItem`, `oListItem`, `image`, and `embed`. The available inline types are `strong`, `em`, `hyperlink`, `label`, and `span`. See an [example](https://prismic.io/docs/fields/rich-text.md#use-custom-ui-components). | Standard HTML elements (e.g. `heading1` becomes a `

`). | | linkResolver (optional) | (field: ContentRelationshipField) => string \| null \| undefined | A [link resolver](https://prismic.io/docs/route-resolver.md#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](https://prismic.io/docs/route-resolver.md). Prefer using a [route resolver](https://prismic.io/docs/route-resolver.md) with the plugin's `clientConfig.routes` option instead. | None | | wrapper (optional, deprecated) | Component \| string | An HTML tag name or a component used to wrap the output. The output is not wrapped by default. Prefer wrapping the component with an HTML element instead. | None | ## `` > **Important** > > This component is deprecated and will be removed in a future version. Use `v-html` instead to render embed fields content. [See an example](https://prismic.io/docs/fields/embed.md#display-embed-fields). Displays HTML from an [embed field](https://prismic.io/docs/field.md#embed). ```vue-html ``` | Prop | Type | Description | Default | | ------------------ | ------------------- | -------------------------------------------------------- | ------- | | field | EmbedField | An embed field to render. | None | | wrapper (optional) | Component \| string | An HTML tag name or a component used to wrap the output. | `"div"` | ## `` Displays a formatted table from a [table field](https://prismic.io/docs/fields/table.md). ```vue-html ``` > See examples and tips on the [table field](https://prismic.io/docs/fields/table.md#display-tables) page. | Prop | Type | Description | Default | | --------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | field | TableField | A table field to render. | None | | fallback (optional) | Component | Rendered if the table field is empty. | None | | 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](https://prismic.io/docs/fields/table.md#use-custom-ui-components). | None | ## `` Renders [slices](https://prismic.io/docs/slice.md) from a slice zone. ```vue-html ``` > See examples and tips on the [slices](https://prismic.io/docs/slices.md#display-slices) page. | Prop | Type | Description | Default | | ------------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | slices | SliceZone | A slice zone to render. | None | | components | object (see definition below) | A map of slice types to Vue components. | None | | defaultComponent (optional) | Component | Rendered if a slice does not have a component mapping. | None | | context (optional) | any | Arbitrary data made available to all slice components. | None | | wrapper (optional, deprecated) | Component \| string | An HTML tag name or a component used to wrap the output. The output is not wrapped by default. Prefer wrapping the component with an HTML element instead. | None | **SliceComponentProps definition:** | Property | Type | Description | Default | | -------- | -------- | ------------------------------------------------ | ------- | | slice | Slice | The slice object being displayed. | None | | slices | Slice\[] | All slices in the slice zone. | None | | index | number | The index of the slice in the slice zone. | None | | context | unknown | The data passed to `SliceZone`'s `context` prop. | None | # Prop helpers ## `getSliceComponentProps` Returns prop types for a slice component. Components rendered by [``](#slicezone) should use this helper. ```ts defineProps(getSliceComponentProps()); ``` ## `getRichTextComponentProps` Returns prop types for a [rich text](https://prismic.io/docs/fields/rich-text.md) field block component. Components rendered by [``](#prismicrichtext) should use this helper. ```ts defineProps(getRichTextComponentProps(type)); ``` | Prop | Type | Description | Default | | --------------- | ------ | ------------------------------------ | ------- | | type (optional) | string | The component's rich text node type. | None | ## `getTableComponentProps` Returns prop types for a [table](https://prismic.io/docs/fields/table.md) field component. Components rendered by [``](#prismicrichtext) should use this helper. ```ts 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. 1. **Install `@prismicio/vue` v5** `@prismicio/vue` v5 is automatically installed when using [`@nuxtjs/prismic` v4](https://prismic.io/docs/technical-reference/nuxtjs-prismic/v4.md). ```sh npm install --save @prismicio/vue@^5 ``` 2. **Provide your own `fetch` polyfill** > **Important** > > 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`](https://www.npmjs.com/package/isomorphic-unfetch) is no longer provided as a default `fetch` implementation. If you still need a `fetch` polyfill, install `isomorphic-unfetch`: ```sh npm install --save isomorphic-unfetch ``` Then, import and configure it with the plugin: ```ts filename=prismic.ts {2,6-8} import { createPrismic } from "@prismicio/vue"; import fetch from "isomorphic-unfetch"; const prismic = createPrismic({ endpoint: "your-repository-name", clientConfig: { fetch, }, }); export default prismic; ``` 3. **Replace `htmlSerializer` plugin option** > **Important** > > This step is only necessary if you were using the `htmlSerializer` plugin option. Use the `richTextSerializer` option instead. ```ts filename=prismic.ts import { createPrismic } from "@prismicio/vue"; const prismic = createPrismic({ endpoint: "your-repository-name", htmlSerializer: serializer // [!code --] richTextSerializer: serializer // [!code ++] }); export default prismic; ``` > **Important** > > 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 ``'s `components` prop. 4. **Replace `components.imageComponent` plugin option** > **Important** > > This step is only necessary if you were using the `components.imageComponent` plugin option. Use your own image component instead with [`@prismicio/client`](https://prismic.io/docs/technical-reference/prismicio-client.md)'s helpers. ```vue-html ``` 5. **Replace `components.linkBlankTargetRelAttribute` plugin option** > **Important** > > This step is only necessary if you were using the `components.linkBlankTargetRelAttribute` plugin option. Use the new `components.linkRel` option. ```ts filename=prismic.ts import { createPrismic } from "@prismicio/vue"; const prismic = createPrismic({ endpoint: "your-repository-name", components: { linkBlankTargetRelAttribute: "noreferrer" // [!code --] linkRel: ({ isExternal }) => isExternal ? "noreferrer" : undefined // [!code ++] } }); ``` > When used with [`@nuxtjs/prismic`](https://prismic.io/docs/technical-reference/nuxtjs-prismic/v4.md), the plugin configuration has to be serializable. Instead, export the function from `~/prismic/linkRel.ts` for the module to recognize it. 6. **Replace ``'s `resolver` prop** > **Important** > > This step is only necessary if you were using ``'s `resolver` prop. Use the new `components` prop instead. ```vue-html ``` > [Slice Machine](https://prismic.io/docs/slice-machine.md) generates a `components` object containing your Vue components for each of your slice libraries. > > ```ts > import { components } from "./slices"; > ``` 7. **Replace ``'s `imageComponent` prop** > **Important** > > This step is only necessary if you were using ``'s `imageComponent` prop. Use your own image component instead with [`@prismicio/client`](https://prismic.io/docs/technical-reference/prismicio-client.md)'s helpers. ```vue-html ``` 8. **Replace ``'s `field` prop when linking documents** > **Important** > > This step is only necessary if you were using ``'s `field` prop with documents. Use the new `document` prop instead. ```vue-html ``` 9. **Update ``'s `rel` attribute behavior** > **Important** > > This step is only necessary if you need to preserve the old ``'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. ```ts filename=prismic.ts {6} import { createPrismic } from "@prismicio/vue"; const prismic = createPrismic({ endpoint: "your-repository-name", components: { linkRel: ({ isExternal }) => (isExternal ? "noreferrer" : undefined), }, }); ``` > When used with [`@nuxtjs/prismic`](https://prismic.io/docs/technical-reference/nuxtjs-prismic/v4.md), 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 ``'s `rel` prop. ```vue-html {3} ``` > [`noreferrer` is equivalent to `noopener > noreferrer`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/noreferrer) which was the previous default. 10. **Update ``'s `target` attribute behavior** The `target` prop is removed. Use the [editor](https://prismic.io/docs/guides/page-builder.md) to control whether links should be opened in a new tab. 11. **Replace ``'s `blankTargetRelAttribute` prop** > **Important** > > This step is only necessary if you were using ``'s `blankTargetRelAttribute` prop. Use the new `rel` prop. ```vue-html ``` 12. **Wrap `` output** > **Important** > > This step is only necessary if you need `` output to remain wrapped. `` output is no longer wrapped. Use your own wrapper tag. ```vue-html {1,3}

``` 13. **Replace ``'s `htmlSerializer` prop** > **Important** > > This step is only necessary if you were using ``'s `htmlSerializer` prop. Migrate to [the new component-based serializer](#prismicrichtext), or use the (now deprecated) `serializer` prop during your migration instead. ```vue-html ``` 14. **Wrap `` output** > **Important** > > This step is only necessary if you need `` output to remain wrapped. `` output is no longer wrapped. Use your own wrapper tag. ```vue-html {1,3}
``` 15. **Replace `usePrismicImage()`** Use [`@prismicio/client`](https://prismic.io/docs/technical-reference/prismicio-client.md)'s helpers directly. ```ts import { usePrismicImage } from "@prismicio/vue"; // [!code --:3] const image = usePrismicImage(slice.primary.image); import { computed } from "vue"; // [!code ++:8] import { usePrismic } from "@prismicio/vue"; const prismic = usePrismic(); const image = computed(() => { return prismic.asImageSrcSet(slice.primary.image); }); ``` 16. **Replace `usePrismicLink()`** Use [`@prismicio/client`](https://prismic.io/docs/technical-reference/prismicio-client.md)'s helpers directly. ```ts import { usePrismicLink } from "@prismicio/vue"; // [!code --:3] const link = usePrismicLink(slice.primary.link); import { computed } from "vue"; // [!code ++:8] import { usePrismic } from "@prismicio/vue"; const prismic = usePrismic(); const link = computed(() => { return prismic.asLinkAttrs(slice.primary.link); }); ``` 17. **Replace `usePrismicText()`** Use [`@prismicio/client`](https://prismic.io/docs/technical-reference/prismicio-client.md)'s helpers directly. ```ts import { usePrismicText } from "@prismicio/vue"; // [!code --:3] const text = usePrismicText(slice.primary.text); import { computed } from "vue"; // [!code ++:8] import { usePrismic } from "@prismicio/vue"; const prismic = usePrismic(); const text = computed(() => { return prismic.asText(slice.primary.text); }); ``` 18. **Replace `usePrismicRichText()`** Use [`@prismicio/client`](https://prismic.io/docs/technical-reference/prismicio-client.md)'s helpers directly. ```ts import { usePrismicRichText } from "@prismicio/vue"; // [!code --:3] const html = usePrismicRichText(slice.primary.text); import { computed } from "vue"; // [!code ++:8] import { usePrismic } from "@prismicio/vue"; const prismic = usePrismic(); const html = computed(() => { return prismic.asHTML(slice.primary.text); }); ``` 19. **Replace all query composables** Use a query library with a Prismic client, such as [TanStack Query](https://tanstack.com/query). ```ts import { usePrismicDocumentByUID } from "@prismicio/vue"; // [!code --:3] const { data } = usePrismicDocumentByUID("page", "home"); import { usePrismic } from "@prismicio/vue"; // [!code ++:9] import { useQuery } from "@tanstack/vue-query"; const prismic = usePrismic(); const { data } = useQuery({ queryKey: ["home"], queryFn: () => prismic.client.getByUID("page", "home"), }); ``` > See [TanStack Query's Quick Start](https://tanstack.com/query/v5/docs/framework/vue/quick-start) for details on `useQuery()`. 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()` | 20. **Replace `DefineComponentSliceComponentProps` type** Use the return type of `getSliceComponentProps` instead. ```ts import { getSliceComponentProps } from "@prismicio/vue"; type DefineComponentSliceComponentProps = ReturnType< typeof getSliceComponentProps >; ```