Asset versions

Manage asset versions in Media Library

Asset versioning lets you maintain different versions of the same media library asset while controlling which version is used across your content. This feature is ideal for managing subtle variations of an asset, such as retouched photos or updated files, without creating entirely new assets.

This guide explains how to use asset versioning to manage different iterations of your media assets while maintaining content integrity.

Prerequisites:

• Access to Sanity Media Library
• Assets uploaded to your Media Library
• A member role that can update assets in your Media Library (without it, version actions are disabled)
• Content that references your assets (optional)

• Open Media Library from your dashboard.
• Select an asset to view its details in the asset sidebar.
• Click the dropdown menu button labeled Aspects in the asset sidebar.
• Select Versions to view all versions of the selected asset.

The versions panel displays all available versions of your asset. The current version has a Current badge, and its indicator is blue when documents use it. Outdated versions that documents still use have an orange indicator, and their actions menu shows an Outdated usage badge. Versions that no documents use show Not in use in their actions menu.

• Navigate to the versions panel for your asset.
• Click Upload new version at the bottom of the panel.
• Select a file from your device to upload as a new version.
• After the upload finishes, the new version appears in the list.

The uploaded file should be a variation of the original asset, such as a color correction or minor edit, rather than an entirely different asset.

To upload versions, set them as current, and update documents with the HTTP API, see Update an asset to a new version with the API.

• In the versions panel, locate and select the version you want to set as current.
• Select Set as current and sync all usage to make it the current version and update all existing usage.

Alternatively, you can set a version as current without updating existing usage by selecting Set as current from the menu that opens when you click the arrow next to Set as current and sync all usage. This is useful for previewing changes before applying them everywhere.

When you have outdated usage (orange indicators), you can update all instances to use the current version:

• In the versions panel, look for the warning about outdated usage at the bottom.
• Click Sync all usage with current to update all instances to use the current version.

To selectively update specific usage:

• Click the usage indicator (dot) next to a version to expand the usage list.
• Select the checkbox next to each document you want to update, then click Sync version usage with Current to update only the selected documents.

Asset versions can be retrieved using GROQ the same way as aspects. The same restrictions and access requirements apply.

*[_type == 'myDocumentType']{
  "versions": documents::get(imageField.media).versions
}

• Use versions for subtle variations of the same asset (retouches, minor edits), not for completely different assets.
• Keep version usage in sync with the current version when possible to maintain consistency.
• Use descriptive version names to easily identify different versions (note: version renaming will be available in a future update).

• Media Library overview
• Meet the library
• Link assets to documents