What are cards?#
CloudCannon uses cards to represent your data. A card is a configurable UI element that gives you a preview of that data. Depending on the type of data stored, this could include an image, title, subtitle, icon, and metadata.
Cards appear in different places across the app, including:
- Snippets
- Snippet Picker
- Structures
- Structure Picker
- Select-style inputs
- Object inputs
- Collection file lists
These cards are configurable using the preview key.
Select-style inputs, Object inputs and Structure and non-structure inputs inside Array inputs support a subset of these options. The specifics are documented on each page.
Configure your card previews#
The preview configuration has a number of different keys which correspond to different parts of the card display.
Preview reference
This key defines the appearance of the gallery section on Cards in the Collection browser, Structures, and Snippets.
Appears in: preview, picker_preview.
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.
collections_config:
blog:
preview:
gallery:
image:
- key: featured_image
fit: padded{
"collections_config": {
"blog": {
"preview": {
"gallery": {
"image": [
{
"key": "featured_image"
}
],
"fit": "padded"
}
}
}
}
}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.
Appears in: preview, metadata[*], gallery, picker_preview.
Show examplesHide examples
In this example, we have configured the icon for Cards in the blog Collection to use the edit_note icon.
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.
collections_config:
blog:
preview:
icon:
- key: logo
- edit_note{
"collections_config": {
"blog": {
"preview": {
"icon": [
{
"key": "logo"
},
"edit_note"
]
}
}
}
}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.
Appears in: preview, metadata[*], gallery, picker_preview.
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.
collections_config:
blog:
preview:
icon_background_color:
- key: bg_color
- text: '#f0f0f0'{
"collections_config": {
"blog": {
"preview": {
"icon_background_color": [
{
"key": "bg_color"
},
{
"text": "#f0f0f0"
}
]
}
}
}
}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.
Appears in: preview, metadata[*], gallery, picker_preview.
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.
collections_config:
blog:
preview:
icon_color:
- key: color
- text: '#ff0000'{
"collections_config": {
"blog": {
"preview": {
"icon_color": [
{
"key": "color"
},
{
"text": "#ff0000"
}
]
}
}
}
}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.
Appears in: preview, metadata[*], gallery, picker_preview.
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.
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.
_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"
}
]
}
}
]
}
}
}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.
Appears in: preview, picker_preview.
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.
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}"
}
]
}
]
}
}
}
}This key represents an individual metadata entry object in the preview.metadata array.
The value is an object that can contain text, image, icon, icon_color, and icon_background_color properties. Each metadata entry is displayed on Cards in the Collection browser, Structures, and Snippets.
Appears in: metadata.
Show examplesHide examples
In this example, we have configured a metadata entry for Cards in the blog Collection to display the URL using a template.
collections_config:
blog:
preview:
metadata:
- template: '[url]'{
"collections_config": {
"blog": {
"preview": {
"metadata": [
{
"template": "[url]"
}
]
}
}
}
}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.
Appears in: preview, picker_preview.
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.
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.
collections_config:
blog:
preview:
subtext:
- key: author{
"collections_config": {
"blog": {
"preview": {
"subtext": [
{
"key": "author"
}
]
}
}
}
}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.
Appears in: preview, metadata[*], gallery, picker_preview.
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.
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.
collections_config:
blog:
preview:
text:
- key: title{
"collections_config": {
"blog": {
"preview": {
"text": [
{
"key": "title"
}
]
}
}
}
}metadata reference
Metadata is a great way to show related data in the card.
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.
Appears in: preview, metadata[*], gallery, picker_preview.
Show examplesHide examples
In this example, we have configured the icon for Cards in the blog Collection to use the edit_note icon.
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.
collections_config:
blog:
preview:
icon:
- key: logo
- edit_note{
"collections_config": {
"blog": {
"preview": {
"icon": [
{
"key": "logo"
},
"edit_note"
]
}
}
}
}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.
Appears in: preview, metadata[*], gallery, picker_preview.
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.
collections_config:
blog:
preview:
icon_color:
- key: color
- text: '#ff0000'{
"collections_config": {
"blog": {
"preview": {
"icon_color": [
{
"key": "color"
},
{
"text": "#ff0000"
}
]
}
}
}
}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.
Appears in: preview, metadata[*], gallery, picker_preview.
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.
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.
_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"
}
]
}
}
]
}
}
}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.
Appears in: preview, metadata[*], gallery, picker_preview.
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.
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.
collections_config:
blog:
preview:
text:
- key: title{
"collections_config": {
"blog": {
"preview": {
"text": [
{
"key": "title"
}
]
}
}
}
}gallery reference
The gallery will render an icon if it is defined, an image over the icon once loaded and if neither exist the text will be displayed.
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.
Appears in: gallery.
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.
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.
collections_config:
blog:
preview:
gallery:
image:
- key: featured_image
background_color:
- red{
"collections_config": {
"blog": {
"preview": {
"gallery": {
"image": [
{
"key": "featured_image"
}
],
"background_color": [
"red"
]
}
}
}
}
}This key defines how images fit within their containers in the gallery section of a Card.
Setting this key to padded adds padding around images to maintain aspect ratio, contain 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, cover ensures images cover the entire container while maintaining aspect ratio with the center of the image aligned with the center of the container, and cover-top ensures images cover the entire container while maintaining aspect ratio with the top of the image aligned with the top of the container.
Defaults to: padded
Allowed values: padded cover contain cover-top
Appears in: gallery.
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.
collections_config:
blog:
preview:
gallery:
image:
- key: featured_image
fit: cover{
"collections_config": {
"blog": {
"preview": {
"gallery": {
"image": [
{
"key": "featured_image"
}
],
"fit": "cover"
}
}
}
}
}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.
Appears in: preview, metadata[*], gallery, picker_preview.
Show examplesHide examples
In this example, we have configured the icon for Cards in the blog Collection to use the edit_note icon.
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.
collections_config:
blog:
preview:
icon:
- key: logo
- edit_note{
"collections_config": {
"blog": {
"preview": {
"icon": [
{
"key": "logo"
},
"edit_note"
]
}
}
}
}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.
Appears in: preview, metadata[*], gallery, picker_preview.
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.
collections_config:
blog:
preview:
icon_color:
- key: color
- text: '#ff0000'{
"collections_config": {
"blog": {
"preview": {
"icon_color": [
{
"key": "color"
},
{
"text": "#ff0000"
}
]
}
}
}
}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.
Appears in: preview, metadata[*], gallery, picker_preview.
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.
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.
_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"
}
]
}
}
]
}
}
}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.
Appears in: preview, metadata[*], gallery, picker_preview.
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.
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.
collections_config:
blog:
preview:
text:
- key: title{
"collections_config": {
"blog": {
"preview": {
"text": [
{
"key": "title"
}
]
}
}
}
}How cascading options work#
Most of the keys within preview are the same type of structure, which we call cascading options. This is either an Array or a single value of the following types:
- A String of the exact value (e.g
"My Item") - A reference to a key within the connected item (e.g
key: titlein YAML or{ "key": "title" }in JSON) - A String with placeholders that will be replaced with values (e.g.
template: {date|date_long}in YAML or{ "template": "{date|date_long}" }in JSON)
# String option
preview_option: Fallback String
# or, Array cascading option
preview_option:
- key: some_key
- key: object.subkey
- template: '{date|date_long}'
- Fallback StringWhen using an Array each item is read in order. If no content is found, the next item in the array is used. If no content is valid, the corresponding preview option will be hidden.
Below is an example of some data representing a Figure that needs previewed:
_type: figure
image_path: /image.png
alt_text: An imageWhen displaying this Figure we want to:
- Always display the
imageicon (A String example) - In the text, display the
image_pathkey falling back to the String ‘Image missing’ (An Array example) - In the subtext, display the
alt_textkey falling back to the String ‘No alternative text’ (Another Array example)
Writing this as a set of preview options will look like this:
preview:
icon: image
text:
- key: image_path
- Image missing
subtext:
- key: alt_text
- No alternative textTemplate strings in previews
You can use template strings in your card previews. Template strings are a mixture of literal text and dynamic placeholders that are replaced with data. You can use template strings to populate your card previews with more complex strings.
The template key can reference keys from within the object you want to preview.
When using a template string, all placeholders within the string must resolve to an output. If any placeholder resolves to an empty result, CloudCannon cannot display that template string. In this case, CloudCannon will use the next item in the array.
Let's walk through an example. We want to add the author of a file to the card metadata field. We want the metadata field to have a person icon and the text "By [author name]". If no author name is available, the text should read "No author".
To achieve this, we will create an array of metadata.text options. The first array item is our template string, with the value of template set to By {author.name}. The second array item is the string No author.
collections_config:
posts:
preview:
metadata:
- text:
- template: By {author.name}
- No author
icon: person{
"collections_config": {
"posts": {
"preview": {
"metadata": [
{
"text": [
{
"template": "By {author.name}"
},
"No author"
],
"icon": "person"
}
]
}
}
}
}In the above example, if the author.name key in our object is set to "Heather", the card preview will display "By Heather" in the metadata field.
For more information, including a list of all available placeholder values, read our documentation on template strings.
Picker specific options#
There are two states where cards can be displayed:
- A card connected to an existing item with it’s own data (e.g an instance of a snippet or structure on a page)
- A card used in a “picker” where the type of item needs to be selected (e.g. adding a snippet or structure)
When a card is used in a “picker”, it is useful to override the options from the preview config. For this we use the picker_preview config which merges on top of the preview options. The options within picker_preview are the same as the options in preview.
For the same figure example we used above we want to:
- Show the String ‘Figure’ for the
text - Disable the
subtextto prevent showing the String ‘No alternative text’
figure:
picker_preview:
text: Figure # Used in a picker
subtext: false # Disables the subtext in the picker
preview: # Used in each figure item
icon: image
text:
- key: image_path
- Image missing
subtext:
- key: alt_text
- No alternative text