Asset Versions

Manage asset versions in Media Library

Asset versioning allows you to 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.

• Access to Sanity Media Library
• Assets uploaded to your Media Library
• Content that references your assets (optional)

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

The versions panel displays all available versions of your asset. The current version is marked with a blue indicator, while any outdated versions in use are marked with an orange indicator.

• 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.
• Once uploaded, the new version will appear 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.

• 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 context menu available by clicking the three dots next to the aforementioned button. 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.
• For each document listed, click Sync version usage with Current to update only that specific instance.

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