2.0.2 • Public • Published

Sanity Visual Option List

This is a Sanity Studio v3 plugin. For the v2 version, please refer to the v2-branch.

NPM Version NPM Version

For notable updates and bug fixes see change log

A visual way to show options to users, for example, what layout to apply for a text/image component (default layout):

preview of default

Or with tooltip, and as smaller icons:

preview of small with tooltip

Or, also for color options:

preview of large with tooltip

See code at over here for how to implement a color list.


From the terminal within the Sanity Studio directory:

npm install sanity-plugin-visual-options

Then add the plugin to your sanity.config.js/ts file:

import { visualOptions } from "sanity-plugin-visual-options";

export default defineConfig({
  // ...
  plugins: [


Schema to produce the above screenshot can be found here with the icons found here

In your schema, you should add a field of type 'visualOptions', and the options property should contain a key of 'list'. Within this is another dictionary, with the key being the reference that will be saved against the item. Each item must contain an icon as a minimum, which is a React Component.

In the example below, which produced the image above with small options, the icons are simple React components returning an SVG, therefore react-icons should work here too.

NOTE: As of Sanity Studio V3 when using React within a schema the schema file must have the extension jsx or tsx not js/ts

  fields: [
      name: "blockLayout",
      title: "Block Layout",
      type: "visualOptions",
      options: {
        showTooltip: true,
        optionSize: "small",
        list: {
          left: {
            name: "Text Left / Image Right",
            icon: OITextLeftOverlap,
            default: true,
          right: {
            name: "Text Right / Image Left",
            icon: OITextRightOverlap,
          top: {
            name: "Text Top / Image Bottom",
            icon: OITextTopOverlap,
          bottom: {
            name: "Text Botom / Image Top",
            icon: OITextBottomOverlap,
          notext: {
            name: "Image, No Text",
            icon: OIImage,
          noimage: {
            name: "Text, No Image",
            icon: OIText,


Within the options for the schema, there are the following options:

  • showLabels: (true|false) - Sets whether to show the labels for each item based on their name.
  • showTooltip: (true|false) - The name of the item will be turned into a tooltip and displayed on hover. Overrides showLabels above.
  • optionSize: ("small"|"medium"|"large") - Sets the size of the option items. Defaults to "medium" if omitted or and invalid option is provided.
  • shape: ("circle"|"box") - Optional, if omitted, default will be "box".

Layout Options


preview of small with tooltip


preview of medium (default) with tooltip


preview of large with tooltip

Future Development/Considerations

  • Allow items multi selections with limits e.g. maximum of two.
  • Add a check mark to show selection and allow de-selection (moving of radio to checkboxes also solving the above item).
  • Allow standard images to be displayed rather than just SVGs.

Package Sidebar


npm i sanity-plugin-visual-options

Weekly Downloads






Unpacked Size

318 kB

Total Files


Last publish


  • nicktayloruk