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

Sanity Visual Option List

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


From the terminal within the Sanity Studio directory:

sanity install visual-options


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.

    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.

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.

Install command