UID

The UID field lets content writers assign a unique identifier to a document. It is often used to build page URLs.

The UID field has these characteristics:

• Only one UID field per page type or custom type is allowed. Slices cannot contain UID fields.
• The value must be unique to the page type or custom type and locale.
• The value must be lowercase and cannot contain spaces. For example, about-us.
• The value cannot contain special characters, except hyphens (-) and underscores (_).
• When a UID value is changed, the old value is retained as a reference. The document can be queried using the previous UID until another document reuses it.

To learn more about managing UIDs, see Edit a Document’s Unique Identifier.

Add a UID field to a content model

Reusable page types and custom types include a UID field with the API ID uid. The UID field cannot be manually added or removed.

Use UID fields

The UID field is most often used to query a document by its UID. The getByUID client method returns a document with a matching document type and UID.

This example queries a Blog Post document with the UID my-first-post.

const blogPost = await client.getByUID("blog_post", "my-first-post");

Tips

• Use the UID in a page’s URL

  A page’s UID can be used in a route resolver as :uid.

  This example configures URLs for Page and Blog Post documents using their UIDs.

  const routes = [
    { type: "page", path: "/:uid" },
    { type: "blog_post", path: "/blog/:uid" },
  ];

  A route resolver can override a more general resolver by specifying a UID. This example overrides the default page route resolver when a page has the UID home.

  const routes = [
    { type: "page", path: "/:uid" },
    { type: "page", uid: "home", path: "/" },
    { type: "blog_post", path: "/blog/:uid" },
  ];

API response

Here is what a UID field looks like from the Document API:

{
  "id": "YCiUyRUAACQAxfZK",
  "uid": "my-first-post",
  "url": "/blog/my-first-post",
  "type": "blog_post",
  "href": "https://example-prismic-repo.cdn.prismic.io/api/v2/...",
  "tags": ["Tag 1", "Tag 2"],
  "first_publication_date": "2021-02-14T03:22:26+0000",
  "last_publication_date": "2022-07-09T00:36:18+0000",
  "slugs": ["my-first-post"],
  "linked_documents": [],
  "lang": "en-us",
  "alternate_languages": [],
  "data": {
    // ...
  }
}

Unlike other field types, the UID field is a top-level document property, not a property within data.