☁️ Loving our new documentation website? Provide feedback in the CloudCannon Community! ✨

Developer ReferenceConfiguration File

gallery

Table of contents

Description:

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

Appears in:
├── preview
│   └── gallery
└── picker_preview
    └── gallery
Type:
Object
Properties:
background_colorArray Preview Entry|Raw Text Preview Entry|False Preview Entry#

This key defines the background color of the gallery area 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 gallery background color with an array of values to provide fallback options. CloudCannon will use the value of gallery_bg_color first, then the {bg_color} template, and finally fall back to the static hex color value.

Copied to clipboard
collections_config:
  blog:
    preview:
      gallery:
        image:
          - key: featured_image
        background_color:
          - key: gallery_bg_color
          - template: '{bg_color}'
          - text: '#ffffff'
{
  "collections_config": {
    "blog": {
      "preview": {
        "gallery": {
          "image": [
            {
              "key": "featured_image"
            }
          ],
          "background_color": [
            {
              "key": "gallery_bg_color"
            },
            {
              "template": "{bg_color}"
            },
            {
              "text": "#ffffff"
            }
          ]
        }
      }
    }
  }
}

In this example, we have configured the gallery background color to use a static CSS color value.

Copied to clipboard
collections_config:
  blog:
    preview:
      gallery:
        image:
          - key: featured_image
        background_color:
          - red
{
  "collections_config": {
    "blog": {
      "preview": {
        "gallery": {
          "image": [
            {
              "key": "featured_image"
            }
          ],
          "background_color": [
            "red"
          ]
        }
      }
    }
  }
}
fitstring#

This key defines how images fit within their containers in the gallery section of a Card.

Valid values are padded (default), contain, cover, or cover-top.

  • The padded value adds padding around images to maintain aspect ratio.
  • The contain value ensures images fit entirely within the container by setting the largest dimension of the image to the largest dimension of the container, while maintaining aspect ratio.
  • The cover value ensures images cover the entire container while maintaining aspect ratio, aligning the center of the image with the center of the container.
  • The cover-top value ensures images cover the entire container while maintaining aspect ratio, aligning the top of the image with the top of the container.

This key defaults to contain.

Defaults to: padded

Allowed values: padded cover contain cover-top

Show examplesHide examples

In this example, we have configured the gallery fit to use cover so images cover the entire container while maintaining aspect ratio, aligning the center of the image with the center of the container.

Copied to clipboard
collections_config:
  blog:
    preview:
      gallery:
        image:
          - key: featured_image
        fit: cover
{
  "collections_config": {
    "blog": {
      "preview": {
        "gallery": {
          "image": [
            {
              "key": "featured_image"
            }
          ],
          "fit": "cover"
        }
      }
    }
  }
}
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"
              }
            ]
          }
        }
      ]
    }
  }
}
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 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"
        }
      }
    }
  }
}
Open in a new tab