Go to prismic.io
Docs
API References

@prismicio/client - v7

Overview

@prismicio/client is Prismic’s SDK for fetching and working with content.

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

Install

@prismicio/client can be installed in any JavaScript project.

npm install --save @prismicio/client

API

createClient()

Creates a Prismic client that can fetch content from a Prismic repository.

const client = createClient(repositoryName, config);

createWriteClient()

Creates a Prismic client that can write content to a Prismic repository. It includes all methods supported in createClient().

const client = createWriteClient(repositoryName, config);

createMigration()

Creates a Migration instance that holds a set of migration procedures to execute, like “create a page” or “create an asset.” The migration can be executed with a write client’s migrate() method.

const migration = createMigration();

Return value

A Migration instance that can hold migration procedures.

Query methods

Fetch content from a Prismic repository using the client’s query methods.

The following example fetches all blog posts from the fr-fr locale using the getAllByType() method.

const client = createClient("example-prismic-repo");
const blogPosts = await client.getAllByType("blog_post", {
  lang: "fr-fr",
});

Query parameters

All query methods accept optional parameters.

get()

Fetches pages based on the params argument. Results are paginated.

await client.get(params);

getFirst()

Fetches the first page returned based on the params argument.

await client.getFirst(params);

getByID()

Fetches a page with a specific ID.

await client.getByID(id, params);

getByIDs()

Fetches pages with specific IDs. Results are paginated.

await client.getByIDs(ids, params);

getAllByIDs()

Fetches pages with specific IDs. This method may make multiple network requests to fetch all matching pages.

await client.getAllByIDs(ids, params);

getByUID()

Fetches a page with a specific UID and type.

await client.getByUID(type, uid, params);

getByUIDs()

Fetches pages with specific UIDs and a specific type. Results are paginated.

await client.getByUIDs(type, uids, params);

getAllByUIDs()

Fetches pages with specific UIDs and a specific type. This method may make multiple network requests to fetch all matching pages.

await client.getAllByUIDs(type, uids, params);

getSingle()

Fetches a specific single type page.

await client.getSingle(type, params);

getByType()

Fetches pages with a specific type. Results are paginated.

await client.getByType(type, params);

getAllByType()

Fetches pages with a specific type. This method may make multiple network requests to fetch all matching documents.

await client.getAllByType(type, params);

getByTag()

Fetches pages with a specific tag. Results are paginated.

await client.getByTag(tag, params);

getAllByTag()

Fetches pages with a specific tag. This method may make multiple network requests to fetch all matching documents.

await client.getAllByTag(tag, params);

getByEveryTag()

Fetches pages with every tag from a list of tags. Results are paginated.

await client.getByEveryTag(tags, params);

getAllByEveryTag()

Fetches pages with every tag from a list of tags. This method may make multiple network requests to fetch all matching pages.

await client.getAllByEveryTag(tags, params);

getBySomeTags()

Fetches pages with at least one tag from a list of tags. Results are paginated.

await client.getBySomeTags(tags, params);

getAllBySomeTags()

Fetches pages with at least one tag from a list of tags. This method may make multiple network requests to fetch all matching documents.

await client.getAllBySomeTags(tags, params);

queryLatestContent()

Configures the client to query the latest published content. This is the client’s default mode.

client.queryLatestContent();

queryContentFromReleaseByID()

Configures the client to query content from a release with a specific ID.

client.queryContentFromReleaseByID(releaseID);

queryContentFromReleaseByLabel()

Configures the client to query content from a release with a specific label. A release’s label is its name shown in the Page Builder.

client.queryContentFromReleaseByLabel(releaseLabel);

queryContentFromRef()

Configures the client to query content from a specific ref.

client.queryContentFromRef(ref);

Repository methods

Fetch repository metadata using the client’s repository methods.

getRepository()

Fetches metadata about the client’s Prismic repository.

await client.getRepository();

getRefs()

Fetches the repository’s active refs.

await client.getRefs();

getRefByLabel()

Fetches a ref by its label. A release ref’s label is its name shown in the Page Builder.

client.getRefByLabel(releaseLabel);

getMasterRef()

Fetches the repository’s master ref.

client.getMasterRef();

getReleases()

Fetches the repository’s active releases.

await client.getReleases();

getReleaseByID()

Fetches a release with a specific ID.

await client.getReleaseByID(releaseID);

getReleaseByLabel()

Fetches a release by its label. A release ref’s label is its name shown in the Page Builder.

await client.getReleaseByLabel(releaseLabel);

getTags()

Fetches the repository’s page tags.

client.getTags();

Returns

An array of string tags.

buildQueryURL()

Builds a Content API query URL with a set of parameters.

client.buildQueryURL(params);

resolvePreviewURL()

Fetches a previewed page’s URL using a preview token and page ID. The token and page ID are provided in the URL opened after clicking the Page Builder’s Preview the page button.

await client.resolvePreviewURL(params);

graphQLFetch()

A preconfigured fetch() function for Prismic’s GraphQL API that can be provided to GraphQL clients. It adds the required prismic-ref and Authorization headers to all requests.

client.graphQLFetch;

migrate()

Executes a set of migration procedures added to a Migration instance created by createMigration().

client.migrate(migration, params);

Migration methods

You can migrate content to Prismic using a special write-capable version of the client.

These methods are available on the Migration instance returned by createMigration().

createAsset()

Creates a new asset in a Migration instance. The asset will not be created in your repository until the migration is executed with migrate().

migration.createAsset(asset);
migration.createAsset(field);
migration.createAsset(file, filename, params);

createDocument()

Creates a new page in a Migration instance. The page will not be created in your repository until the migration is executed with migrate().

migration.createDocument(document, title, params);

updateDocument()

Updates an existing page in a Migration instance. The page will not be updated in your repository until the migration is executed with migrate().

migration.updateDocument(document, title);

createDocumentFromPrismic()

Creates a new page in a Migration instance based on an existing Prismic page. Assets and content relationships will be created and resolved automatically. The page and its assets will not be created in your repository until the migration is executed with migrate().

migration.createDocumentFromPrismic(document, title);

getByUID()

Gets a page with a specific UID and type from within a Migration instance. Use this method to retrieve a page that has not yet been migrated using migrate().

migration.getByUID(type, uid);

getSingle()

Gets a specific single type page from within a Migration instance. Use this method to retrieve a page that has not yet been migrated using migrate().

migration.getSingle(type);

Content helpers

@prismicio/client provides helpers that manipulate Prismic content. The helpers can be used throughout your website or in scripts.

Content helpers can be imported directly from @prismicio/client:

import { asDate } from "@prismicio/client";

asDate()

Converts a date or timestamp field to a JavaScript Date.

asDate(field);

asLink()

Converts a link field, link to media field, content relationship field, or Prismic page to a URL.

asLink(fieldOrDocument, params);

asLinkAttrs()

Converts a link field, link to media field, content relationship field, or Prismic page to a set of link attributes. The attributes are intended to be passed to <a> HTML elements.

asLinkAttrs(fieldOrDocument, params);

asHTML()

Converts a rich text field to HTML. The output can be customized using a set of serialization functions.

asHTML(field, config);

asText()

Converts a rich text field to plain text.

asText(field, config);

asImageSrc()

Converts an image field to an image URL. The image can be transformed using imgix’s Rendering API.

asImageSrc(field, transformations);

asImageWidthSrcSet()

Converts an image field to a srcset designed for <img> HTML elements. The srcset uses width descriptors, like 400w and 600w.

The image can be transformed using imgix’s Rendering API.

asImageWidthSrcSet(field, config);

asImagePixelDensitySrcSet()

Converts an image field to a srcset designed for <img> HTML elements. The srcset uses pixel density descriptors, like 1x and 2x.

The image can be transformed using imgix’s Rendering API.

asImagePixelDensitySrcSet(field, config);

mapSliceZone()

Converts slices in a slice zone to objects of your choosing. It is designed to add data, remove unused content, or preprocess content on a server.

await mapSliceZone(slices, mappers, context);

isFilled

A set of functions that determine if a field has content or not. Each field type has its own function within isFilled.

isFilled.richText(field);

Query filters

You can adjust which pages are returned by query methods using filters. @prismicio/client provides helpers to write filters.

import { filter } from "@prismicio/client";

Each filter type has its own function within filter.

The following example uses the not() filter to fetch all Page pages except the pages with the home UID.

await client.getAllByType("page", {
  filters: [filter.not("my.page.uid", "home")],
});

at()

Checks that a field or page metadata property matches a value exactly.

filter.at(path, value);

not()

Checks that a field or page metadata property doesn’t match a value exactly.

filter.not(path, value);

any()

Includes pages with a field or metadata property matching a value from a given list.

filter.any(path, values);

in()

Includes pages with an ID or UID matching a value from a given list. This filter is much more efficient at that than the any() filter.

filter.in(path, values);

fulltext()

Includes pages with a matching string anywhere in the page. It can also check within a specific rich text, text, or select field.

filter.fulltext(path, searchTerm);

has()

Includes pages that have a value for a specific field.

filter.has(path);

missing()

Includes pages that do not have a value for a specific field. The inverse of has().

filter.missing(path);

similar()

Includes pages that have similar content to a given page. This filter allows you to build content discovery features, like a “Related posts” section.

filter.similar(documentID, specificity);

geopointNear()

Includes pages with a geopoint field value near the given coordinates.

filter.geopointNear(path, latitude, longitude, radius);

numberLessThan()

Includes pages with a number field value less than a given number.

filter.numberLessThan(path, number);

numberGreaterThan()

Includes pages with a number field value greater than a given number.

filter.numberGreaterThan(path, number);

numberInRange()

Includes pages with a number field value within a given range.

filter.numberInRange(path, lowerLimit, upperLimit);

dateAfter()

Includes pages with a date field, timestamp field, or timestamp metadata property after a given date.

filter.dateAfter(path, date);

dateBefore()

Includes pages with a date field, timestamp field, or timestamp metadata property before a given date.

filter.dateBefore(path, date);

dateBetween()

Includes pages with a date field, timestamp field, or timestamp metadata property between given dates.

filter.dateBetween(path, startDate, endDate);

dateDayOfMonth()

Includes pages with a date field, timestamp field, or timestamp metadata property that is on a specific day of the month.

filter.dateDayOfMonth(path, dayOfMonth);

dateDayOfMonthAfter()

Includes pages with a date field, timestamp field, or timestamp metadata property that is after a specific day of the month.

filter.dateDayOfMonthAfter(path, dayOfMonth);

dateDayOfMonthBefore()

Includes pages with a date field, timestamp field, or timestamp metadata property that is before a specific day of the month.

filter.dateDayOfMonthBefore(path, dayOfMonth);

dateDayOfWeek()

Includes pages with a date field, timestamp field, or timestamp metadata property that is on a specific day of the week.

filter.dateDayOfWeek(path, dayOfWeek);

dateDayOfWeekAfter()

Includes pages with a date field, timestamp field, or timestamp metadata property that is after a specific day of the week.

filter.dateDayOfWeekAfter(path, dayOfWeek);

dateDayOfWeekBefore()

Includes pages with a date field, timestamp field, or timestamp metadata property that is before a specific day of the week.

filter.dateDayOfWeekBefore(path, dayOfWeek);

dateMonth()

Includes pages with a date field, timestamp field, or timestamp metadata property that is within a specific month.

filter.dateMonth(path, month);

dateMonthAfter()

Includes pages with a date field, timestamp field, or timestamp metadata property that is after a specific month.

filter.dateMonthAfter(path, month);

dateMonthBefore()

Includes pages with a date field, timestamp field, or timestamp metadata property that is before a specific month.

filter.dateMonthBefore(path, month);

dateYear()

Includes pages with a date field, timestamp field, or timestamp metadata property that is within a specific year.

filter.dateYear(path, year);

dateHour()

Includes pages with a date field, timestamp field, or timestamp metadata property that is within a specific hour.

filter.dateHour(path, hour);

dateHourAfter()

Includes pages with a date field, timestamp field, or timestamp metadata property that is after a specific hour.

filter.dateHourAfter(path, hour);

dateHourBefore()

Includes pages with a date field, timestamp field, or timestamp metadata property that is before a specific hour.

filter.dateHourBefore(path, hour);
Was this page helpful?