Add Sanity integration into Uniform

The Sanity integration for Uniform brings your structured content from Sanity into the Uniform's visual experience composition layer. Team members can now leverage your Sanity content along with content from any of your other sources, to create personalized experiences visually without developers.

This integration installs the following Sanity-specific archetypes allowing to bring content from your Sanity dataset directly into your Uniform components with a few clicks:

  • Single Document - for selecting a single Sanity document
  • Multiple Documents - for selecting multiple documents, useful when building lists
  • Document Query - for creating a dynamic query (for example, the 5 most recent documents of a given type)

Prerequisites

You must have the following to complete this setup:

  • Obtain Sanity API Token with Viewer permissions.
  • Get your Sanity Studio URL.
  • Uniform account with Team Admin access. If you don't already have one, you can request an account at https://uniform.dev/try.
  1. In Uniform, open your project.

  2. Navigate to the Integrations tab.

  3. Scroll to the section Browse integrations.

  4. Search for Sanity, click on the integration.

  5. Click Add to project.

    install-sanity-integration
    Install Sanity integration.

Before you start

For more general tips on working with external data sources, check out the guide on connecting to an external data source.

Once you've installed the integration, the next step is to connect your Sanity project to your Uniform project by creating a new data source.

  1. Navigate to Experience > Data Types. A data type is an element that can be retrieved from a data source, so the first step is to identify a data source.

  2. Create a new data source by clicking the Add data type button and select the "Create new" option under the Sanity label.

    sanity-add-datasource
    Add a data type.
    sanity-add-datatype
    Where to create a new data type from the available data sources.
  3. Enter the connection details for your Sanity project. The Sanity Studio URL is optional but recommended, as it will allow to link to your Sanity content from Uniform.

    sanity-configure-datasource
    Configure data source.
  4. Name your data source. Choose a name that helps to inform your editorial users where the content is coming from. It can be just 'Sanity` or the name of your Sanity project.

    add-sanity-datasource
    Add a data type.

Before you start connecting Sanity data to your Uniform components and compositions, it's important to first create some data types. Data types define which types of Sanity content you want to use within Uniform.

Depending on the archetype, you may need to select a single document from Sanity dataset, or get a list using a query, such as: five latest news articles sorted by date.

  1. Go to Experience > Data Types and click the Add data type button from below the Sanity data source that you set-up earlier.

  2. Next, you will want to select and configure an archetype from the options below.

The single document archetype will always return a single document from Sanity, based on a selection by the editor in Uniform. This is useful for non-list elements that render as an independent document, such as a single "hero" entry or "article" entry. It can accept a variable from a dynamic token (such as a slug) and retrieve the corresponding entry.

create-datatype
Single Document data type.

You can optionally specify projections using GROQ syntax.

The multiple documents archetype lets an editor hand pick multiple entries to render as a list. This is useful when a small selection of specific entries is required, such as in a "featured articles" carousel.

sanity-datatype-multi
Multiple Documents data type.

The query archetype will return a list of documents based on the query set by the editor in Uniform. This can be useful for dynamic queries where the most up-to-date information is needed, such as a "latest content" section. Uniform will not persist the specific selection of documents, instead the query will be saved, allowing to re-run it when edge cache expires, getting fresh content from Sanity matching the query.

Once you configure the archetype, you can test to see what response would be returned when it's used in an experience:

sanity-datatype-query
Document Query data type.

Now you are ready to bring content directly into your components in Uniform:

  1. Open any component pattern or a composition that you want to source content from Sanity to.
  2. Click on the connect icon next to the parameter.
  3. You will be prompted to create a new data resource using one of the data types you created.
connect-sanity-content
Single Document data type.