Custom asset sources

Sanity Studio comes with a rudimentary asset selector out of the box. It lets you browse and select images or files you have already uploaded. You can also add multiple asset sources, or replace the default one, globally or for a specific asset field.

You can find available asset source plugins in this overview or by searching for them on npmjs.com. If the package name starts with sanity-plugin-<asset-plugin-name>, you can install them using the Sanity CLI tool in your studio project folder: sanity install <asset-plugin-name>. This will add it to the dependencies in package.json and to the plugins array in sanity.json. Some asset plugins will require that you add some configuration, for example, an API token. You can find this configuration file in the config/ folder in your studio project folder, in most cases.

When adding custom asset source plugins to your studio, the Select button for the upload field will become a drop-down button, showing the multiple sources:

You can override every image or file field to only support a specified set of sources by leveraging the parts system. More specifically, by implementing the part part:@sanity/form-builder/input/image/asset-sources or part:@sanity/form-builder/input/file/asset-sources and referencing the implementation in your Studio's sanity.json file located on the root level of your folder.

Let's say you want to enable the Cloudinary asset source only. First, install the plugin by running sanity install asset-source-cloudinary. Remember to add your API keys in the Cloudinary config file located in the Studio’s config folder. Then, in sanity.json, add this code snippet to the parts array:

{
  "implements": "part:@sanity/form-builder/input/image/asset-sources",
  "path": "./parts/assetSources.js"
}

This code snippet tells the studio to go to a file called assetSources.js that's located in a folder called parts inside your studio’s project folder. You should create this file (and folder if you don't have done so already). This file should export an array of asset sources. So if you only want to enable the Cloudinary source, it would have to look like this:

import Cloudinary from 'part:asset-source-cloudinary/image-asset-source'

export default [Cloudinary]

The part name for a specific plugin can be found in the sanity.json file on the root of that plugin's source (and should preferably be mentioned in its documentation).

The built-in default sources have the part names part:@sanity/form-builder/input/image/asset-source-default and part:@sanity/form-builder/input/file/asset-source-default. Import the part(s), and add that to the array if you want to keep it.

You can customize sources for single image or file type field in the schema via the options.sources property:

import Default from 'part:@sanity/form-builder/input/image/asset-source-default'
import Cloudinary from 'part:asset-source-cloudinary/image-asset-source'

{
  name: 'bannerImage',
  title: 'Banner image',
  type: 'image',
  options: {sources: [Default, Cloudinary]}
}

You can remove the Browse button on an image field (making the field upload-only) by specifying options.sources as an empty array:

{
  name: 'uploadedImage',
  title: 'Upload an Image',
  type: 'image',
  options: {sources: []}
}

The plugin exports an object like this implementing part:@sanity/form-builder/input/image/asset-source

export default {
  name: 'cloudinary', // Unique source name
  title: 'Cloudinary', // Title displayed in lists, buttons etc
  component: Cloudinary, // Selection component
  icon: Icon // Icon for lists, buttons etc.
}

It is then listed in the plugin's sanity.json file:

{
  "paths": {
    "source": "./src",
    "compiled": "./dist/lib"
  },
  "parts": [
    {
      "name": "part:asset-source-unsplash/image-asset-source",
      "implements": "part:@sanity/form-builder/input/image/asset-source",
      "path": "index.js"
    }
  ]
}

The name is something you pick yourself but follow the naming conventions described here.

The plugin exports an object implementing part:@sanity/form-builder/input/file/asset-source similar to the image asset source.

It is then listed in the plugin's sanity.json file:

{
  "paths": {
    "source": "./src",
    "compiled": "./dist/lib"
  },
  "parts": [
    {
      "name": "part:asset-source-unsplash/file-asset-source",
      "implements": "part:@sanity/form-builder/input/file/asset-source",
      "path": "index.js"
    }
  ]
}

The part exports a component that will let the user select some asset(s) from somewhere.

If the user selects something, the component calls the props.onSelect function with an array of asset objects like this:

type Asset {
  kind: 'url' | 'base64' | 'file' | 'assetDocumentId'
  value: string | File
  assetDocumentProps?: {
    originalFilename?: string,
    source?: {
      name: string,
      id: string,
      url?: string
    },
    label?: string,
    title?: string,
    description?: string,
    creditLine?: string
  }
}

An asset can be a URL, user agent File object, base64 encoded binary data or an assetDocumentId. It can have assetDocumentProps that will end up as properties on the resulting asset document. The allowed document props are:

Using the part:@sanity/components/dialogs/fullscreen we can make a closeable interface, and do a simple component where you can select a single image:

import React, {useCallback} from "react";
import {
  Dialog,
  Card,
} from "@sanity/ui";

export default function GitHubAssetSource({ onSelect, onClose }) {
  const handleSelect = useCallback(() => {
    onSelect([
      {
        kind: "url",
        value:
          "https://github.githubassets.com/images/modules/site/sponsors/logo-mona.svg",
        assetDocumentProps: {
          originalFilename: "logo-mona.svg", // Use this filename when the asset is saved as a file by someone.
          source: {
            // The source this image is from
            name: "github.githubassets.com",
            // A string that uniquely idenitfies it within the source.
            // In this example the URL is the closest thing we have as an actual ID.
            id: "https://github.githubassets.com/images/modules/site/sponsors/logo-mona.svg",
          },
          description: "Mona Lisa Octocat",
          creditLine: "By Github.com",
        },
      },
    ]);
  }, [onSelect]);

  const handleClose = useCallback(() => {
    onClose();
  }, [onClose]);

  return (
    <Dialog
      id="github-asset-source"
      header="Select image from Github"
      onClose={handleClose}
      width={4}
      open
    >
      <Card>
        <img
          src="https://github.githubassets.com/images/modules/site/sponsors/logo-mona.svg"
          onClick={handleSelect}
        />
      </Card>
    </Dialog>
  );
}