Go to prismic.ioDeveloper 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 document” 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 documents based on the params argument. Results are paginated.

await client.get(params);

getFirst()

Fetches the first document returned based on the params argument.

await client.getFirst(params);

getByID()

Fetches a document with a specific ID.

await client.getByID(id, params);

getByIDs()

Fetches documents with specific IDs. Results are paginated.

await client.getByIDs(ids, params);

getAllByIDs()

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

await client.getAllByIDs(ids, params);

getByUID()

Fetches a document with a specific UID and type.

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

getByUIDs()

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

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

getAllByUIDs()

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

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

getSingle()

Fetches a specific single type document.

await client.getSingle(type, params);

getByType()

Fetches documents with a specific type. Results are paginated.

await client.getByType(type, params);

getAllByType()

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

await client.getAllByType(type, params);

getByTag()

Fetches documents with a specific tag. Results are paginated.

await client.getByTag(tag, params);

getAllByTag()

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

await client.getAllByTag(tag, params);

getByEveryTag()

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

await client.getByEveryTag(tags, params);

getAllByEveryTag()

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

await client.getAllByEveryTag(tags, params);

getBySomeTags()

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

await client.getBySomeTags(tags, params);

getAllBySomeTags()

Fetches documents 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 document tags.

client.getTags();

Returns

An array of string tags.

buildQueryURL()

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

client.buildQueryURL(params);

resolvePreviewURL()

Fetches a previewed document’s URL using a preview token and document ID. The token and document 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 document in a Migration instance. The document will not be created in your repository until the migration is executed with migrate().

migration.createDocument(document, title, params);

updateDocument()

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

migration.updateDocument(document, title);

createDocumentFromPrismic()

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

migration.createDocumentFromPrismic(document, title);

getByUID()

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

migration.getByUID(type, uid);

getSingle()

Gets a specific single type document from within a Migration instance. Use this method to retrieve a document 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 document to a URL.

asLink(fieldOrDocument, params);

asLinkAttrs()

Converts a link field, link to media field, content relationship field, or Prismic document 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.

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 documents 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 documents except the document with the home UID.

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

at()

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

filter.at(path, value);

not()

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

filter.not(path, value);

any()

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

filter.any(path, values);

in()

Includes documents 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 documents with a matching string anywhere in the document. It can also check within a specific rich text, text, or select field.

filter.fulltext(path, searchTerm);

has()

Includes documents that have a value for a specific field.

filter.has(path);

missing()

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

filter.missing(path);

similar()

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

filter.similar(documentID, specificity);

geopointNear()

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

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

numberLessThan()

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

filter.numberLessThan(path, number);

numberGreaterThan()

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

filter.numberGreaterThan(path, number);

numberInRange()

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

filter.numberInRange(path, lowerLimit, upperLimit);

dateAfter()

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

filter.dateAfter(path, date);

dateBefore()

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

filter.dateBefore(path, date);

dateBetween()

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

filter.dateBetween(path, startDate, endDate);

dateDayOfMonth()

Includes documents 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 documents 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 documents 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 documents 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 documents 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 documents 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 documents with a date field, timestamp field, or timestamp metadata property that is within a specific month.

filter.dateMonth(path, month);

dateMonthAfter()

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

filter.dateMonthAfter(path, month);

dateMonthBefore()

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

filter.dateMonthBefore(path, month);

dateYear()

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

filter.dateYear(path, year);

dateHour()

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

filter.dateHour(path, hour);

dateHourAfter()

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

filter.dateHourAfter(path, hour);

dateHourBefore()

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

filter.dateHourBefore(path, hour);