sanity-plugin-visual-options

Sanity Visual Option List

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

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):

Or with tooltip, and as smaller icons:

Or, also for color options:

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

Installation

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: [
    visualOptions(),
  ]
})

Usage

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,
          },
        },
      },
    },
    ...
  ],
}

Options

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

Small

Medium

Large

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.