picker_preview

Description:

This key defines the appearance of a Card when choosing an item to create. This uses preview as a base, and keys inside this object are overrides.

You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select inputs, Structures, the Structure modal, Snippets, and the Snippet modal.

For more information about previews, please read our documentation on configuring card previews.

Appears in:

├── _inputs
│   └── *
│       ├── Select Input
│       │   └── options
│       │       └── picker_preview
│       ├── Multiselect Input
│       │   └── options
│       │       └── picker_preview
│       ├── Choice Input
│       │   └── options
│       │       └── picker_preview
│       └── Multichoice Input
│           └── options
│               └── picker_preview
├── [*]
│   └── picker_preview
└── Snippet
    └── picker_preview

Type:

Object

Properties:

galleryObject#

This key defines the appearance of the gallery section on Cards in the Collection browser, Structures, and Snippets.

Show examplesHide examples

In this example, we have configured the gallery section for Cards in the blog Collection to display the image stored under the featured_image key with a padded fit.

Copied to clipboard

collections_config:
  blog:
    preview:
      gallery:
        image:
          - key: featured_image
        fit: padded

{
  "collections_config": {
    "blog": {
      "preview": {
        "gallery": {
          "image": [
            {
              "key": "featured_image"
            }
          ],
          "fit": "padded"
        }
      }
    }
  }
}

iconArray Preview Entry|Raw Text Preview Entry|False Preview Entry#

This key defines the icon displayed on Cards in the Collection browser, Structures, and Snippets.

The value can be an array or a single value, and reference a key, template, text string, that results in one of Google's Material Symbols. When multiple entries are provided, CloudCannon will use them in order as fallback options.

For Cards in the Collection Browser, this key defaults to the value of collections_config.*.icon. Otherwise, this key has no default.

Show examplesHide examples

In this example, we have configured the icon for Cards in the blog Collection to use the edit_note icon.

Copied to clipboard

collections_config:
  blog:
    preview:
      icon: edit_note

{
  "collections_config": {
    "blog": {
      "preview": {
        "icon": "edit_note"
      }
    }
  }
}

In this example, we have configured the icon for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of logo first, then fall back to the edit_note icon.

Copied to clipboard

collections_config:
  blog:
    preview:
      icon:
        - key: logo
        - edit_note

{
  "collections_config": {
    "blog": {
      "preview": {
        "icon": [
          {
            "key": "logo"
          },
          "edit_note"
        ]
      }
    }
  }
}

icon_background_colorArray Preview Entry|Raw Text Preview Entry|False Preview Entry#

This key defines the background color of the icon displayed on Cards in the Collection browser, Structures, and Snippets.

The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.

Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.

Show examplesHide examples

In this example, we have configured the icon background color for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of bg_color first, then fall back to the static hex color value.

Copied to clipboard

collections_config:
  blog:
    preview:
      icon_background_color:
        - key: bg_color
        - text: '#f0f0f0'

{
  "collections_config": {
    "blog": {
      "preview": {
        "icon_background_color": [
          {
            "key": "bg_color"
          },
          {
            "text": "#f0f0f0"
          }
        ]
      }
    }
  }
}

icon_colorArray Preview Entry|Raw Text Preview Entry|False Preview Entry#

This key defines the color of the icon displayed on Cards in the Collection browser, Structures, and Snippets.

The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.

Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.

Show examplesHide examples

In this example, we have configured the icon color for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of color first, then fall back to the static hex color value.

Copied to clipboard

collections_config:
  blog:
    preview:
      icon_color:
        - key: color
        - text: '#ff0000'

{
  "collections_config": {
    "blog": {
      "preview": {
        "icon_color": [
          {
            "key": "color"
          },
          {
            "text": "#ff0000"
          }
        ]
      }
    }
  }
}

imageArray Preview Entry|Raw Text Preview Entry|False Preview Entry#

This key defines the image displayed on Cards in the Collection browser, Structures, and Snippets.

The value can be an array or a single value, and reference a key, template, or text string that results in a file path or URL to an image file. When multiple entries are provided, CloudCannon will use them in order as fallback options.

Show examplesHide examples

In this example, we have configured the image for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of featured_image first, then the {thumbnail} template, and finally fall back to the static text value.

Copied to clipboard

collections_config:
  blog:
    preview:
      image:
        - key: featured_image
        - template: '{thumbnail}'
        - text: default-image.jpg

{
  "collections_config": {
    "blog": {
      "preview": {
        "image": [
          {
            "key": "featured_image"
          },
          {
            "template": "{thumbnail}"
          },
          {
            "text": "default-image.jpg"
          }
        ]
      }
    }
  }
}

In this example, we have configured the image for Structure Cards to display the profile_picture key.

Copied to clipboard

_structures:
  staff:
    values:
      - value:
          _type: Employee
          name: 
          profile_picture: 
        preview:
          image:
            - key: profile_picture

{
  "_structures": {
    "staff": {
      "values": [
        {
          "value": {
            "_type": "Employee",
            "name": null,
            "profile_picture": null
          },
          "preview": {
            "image": [
              {
                "key": "profile_picture"
              }
            ]
          }
        }
      ]
    }
  }
}

metadataArray<metadata[*]>#

This key defines metadata entries displayed on Cards in the Collection browser, Structures, and Snippets.

The value is an array of metadata entry objects. Each metadata entry can contain text, image, icon, icon_color, and icon_background_color properties.

Metadata entries are typically used to display additional information about a card, such as publication dates, URLs, or other contextual data.

Show examplesHide examples

In this example, we have configured two metadata entries for Cards in the blog Collection to display the URL and publication date.

Copied to clipboard

collections_config:
  blog:
    preview:
      metadata:
        - text:
            - key: url
        - icon: event
          icon_color: light-blue
          text:
            - template: Published on {date|date_long}

{
  "collections_config": {
    "blog": {
      "preview": {
        "metadata": [
          {
            "text": [
              {
                "key": "url"
              }
            ]
          },
          {
            "icon": "event",
            "icon_color": "light-blue",
            "text": [
              {
                "template": "Published on {date|date_long}"
              }
            ]
          }
        ]
      }
    }
  }
}

subtextArray Preview Entry|Raw Text Preview Entry|False Preview Entry#

This key defines the secondary text displayed below the main text on Cards in the Collection browser, Structures, and Snippets.

The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.

Show examplesHide examples

In this example, we have configured the subtext for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of author first, then the {writer} template, and finally fall back to the static text value.

Copied to clipboard

collections_config:
  blog:
    preview:
      subtext:
        - key: author
        - template: '{writer}'
        - text: Unknown author

{
  "collections_config": {
    "blog": {
      "preview": {
        "subtext": [
          {
            "key": "author"
          },
          {
            "template": "{writer}"
          },
          {
            "text": "Unknown author"
          }
        ]
      }
    }
  }
}

In this example, we have configured the subtext for Cards in the blog Collection to display the author key.

Copied to clipboard

collections_config:
  blog:
    preview:
      subtext:
        - key: author

{
  "collections_config": {
    "blog": {
      "preview": {
        "subtext": [
          {
            "key": "author"
          }
        ]
      }
    }
  }
}

tagsArray<tags[*]>#

This key defines tags displayed on Cards in the Collection browser, Structures, and Snippets.

Show examplesHide examples

In this example, we have configured tags for Cards in the blog Collection to display category tags.

Copied to clipboard

collections_config:
  blog:
    preview:
      tags:
        - featured
        - tutorial

{
  "collections_config": {
    "blog": {
      "preview": {
        "tags": [
          "featured",
          "tutorial"
        ]
      }
    }
  }
}

textArray Preview Entry|Raw Text Preview Entry|False Preview Entry#

This key defines the main text displayed on Cards in the Collection browser, Structures, and Snippets.

The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.

Show examplesHide examples

In this example, we have configured the main text for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of title first, then the {name} template, and finally fall back to the static text value.

Copied to clipboard

collections_config:
  blog:
    preview:
      text:
        - key: title
        - template: '{name}'
        - text: Untitled

{
  "collections_config": {
    "blog": {
      "preview": {
        "text": [
          {
            "key": "title"
          },
          {
            "template": "{name}"
          },
          {
            "text": "Untitled"
          }
        ]
      }
    }
  }
}

In this example, we have configured the main text for Cards in the blog Collection to display the title key.

Copied to clipboard

collections_config:
  blog:
    preview:
      text:
        - key: title

{
  "collections_config": {
    "blog": {
      "preview": {
        "text": [
          {
            "key": "title"
          }
        ]
      }
    }
  }
}

Examples:

In this example, we have configured the appearance of Cards in inputs using the Structure staff when adding items.

Copied to clipboard

_structures:
  staff:
    values:
      - value:
          _type: Employee
          name: 
          job_description: 
          profile_picture: 
        picker_preview:
          text:
            - key: name
            - Employee
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: support_agent
      - value:
          _type: Manager
          name: 
          job_description: 
          profile_picture: 
          url: 
        picker_preview:
          text:
            - key: name
            - Manager
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: face

{
  "_structures": {
    "staff": {
      "values": [
        {
          "value": {
            "_type": "Employee",
            "name": null,
            "job_description": null,
            "profile_picture": null
          },
          "picker_preview": {
            "text": [
              {
                "key": "name"
              },
              "Employee"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "support_agent"
          }
        },
        {
          "value": {
            "_type": "Manager",
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          },
          "picker_preview": {
            "text": [
              {
                "key": "name"
              },
              "Manager"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "face"
          }
        }
      ]
    }
  }
}

User Articles

User Guides

User Glossary

Developer Articles

Developer Guides

Developer Reference

`picker_preview`

Table of contents