Configure your card previews

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
- Hugo Shortcodes
- Eleventy Shortcodes
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#

text — Array, or String#

The highest level of text shown in the preview.

subtext — Array, or String#

The second highest level of text which is displayed over at most two lines.

_inputs.*.options.preview.icon — Array, string or boolean#

This key determines the icon displaye beside the text and subtext on a Card. The value must match a name from the Google's Material Icons list.

This key defaults to checking the icon key, then falls back to the notes icon.

If set to false, no icon is displayed.

If image is defined, the image replaces icon when loaded successfully.

This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:

A String of the exact value (e.g "edit_note")
A reference to a key within the connected item (e.g key: icon in YAML or { "key": "icon" } in JSON)
A String with placeholders that will be replaced with values (e.g. template: {icon_type} in YAML or { "template": "{icon_type}" } in JSON)

Show exampleHide example

In this example, we configure a static icon for the card.

cloudcannon.config.yaml

copied

preview:
  icon: edit_note

cloudcannon.config.json

copied

{
  "preview": {
    "icon": "edit_note"
  }
}

In this example, we use a dynamic icon from the data.

cloudcannon.config.yaml

copied

preview:
  icon:
    - key: icon_type
    - support_agent

cloudcannon.config.json

copied

{
  "preview": {
    "icon": [
      {
        "key": "icon_type"
      },
      "support_agent"
    ]
  }
}

_inputs.*.options.preview.icon_color — Array, string or boolean#

This key determines the color of the icon displayed on a Card.

This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:

A String of the exact value (e.g "#ff0000")
A reference to a key within the connected item (e.g key: color in YAML or { "key": "color" } in JSON)
A String with placeholders that will be replaced with values (e.g. template: {color_code} in YAML or { "template": "{color_code}" } in JSON)

By default, this key is #000000 (black).

Show exampleHide example

In this example, we configure a dynamic icon color from the data with a fallback to red.

cloudcannon.config.yaml

copied

preview:
  icon: edit_note
  icon_color:
    - key: color
    - '#ff0000'

cloudcannon.config.json

copied

{
  "preview": {
    "icon": "edit_note",
    "icon_color": [
      {
        "key": "color"
      },
      "#ff0000"
    ]
  }
}

In this example, we use a static icon color.

cloudcannon.config.yaml

copied

preview:
  icon: nature_people
  icon_color:
    - '#00ff00'

cloudcannon.config.json

copied

{
  "preview": {
    "icon": "nature_people",
    "icon_color": [
      "#00ff00"
    ]
  }
}

_inputs.*.options.preview.icon_background_color — Array, string or boolean#

This key determines the background color of the icon displayed on a Card. This is useful if your icon_color value has poor contrast on a white background.

This key supports cascading options, which can be either an Array or a single value.Value can be one of the following:

A String of the exact value (e.g "#ff0000")
A reference to a key within the connected item (e.g key: color in YAML or { "key": "color" } in JSON)
A String with placeholders that will be replaced with values (e.g. template: {color_code} in YAML or { "template": "{color_code}" } in JSON)

This key has no default.

Show exampleHide example

In this example, we configure a dynamic icon background color from the data with a fallback to red.

cloudcannon.config.yaml

copied

preview:
  icon: edit_note
  icon_background_color:
    - key: color
    - '#ff0000'

cloudcannon.config.json

copied

{
  "preview": {
    "icon": "edit_note",
    "icon_background_color": [
      {
        "key": "color"
      },
      "#ff0000"
    ]
  }
}

In this example, we use a static icon background color.

cloudcannon.config.yaml

copied

preview:
  icon: nature_people
  icon_background_color:
    - '#00ff00'

cloudcannon.config.json

copied

{
  "preview": {
    "icon": "nature_people",
    "icon_background_color": [
      "#00ff00"
    ]
  }
}

image — Array, or String#

Defines an image to display beside the text and subtext on the card. Once the image loads it will cover the icon.

metadata — Array#

A list of items that can contain an image, icon and text. Great for related data. See metadata reference below.

gallery — Object#

Defines large image/icon preview for the card. See gallery metadata below.

metadata reference#

Metadata is a great way to show related data in the card.

text — Array, or String#

The text to be displayed on the metadata item.

icon — Array, String, or Boolean#

Defines an icon from Google’s Material Icons beside the text on the metadata. Must match Material Icon name.

icon_color — Array, or String#

This key determines the color of the icon displayed on a Card.

This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:

A String of the exact value (e.g "#ff0000")
A reference to a key within the connected item (e.g key: color in YAML or { "key": "color" } in JSON)
A String with placeholders that will be replaced with values (e.g. template: {color_code} in YAML or { "template": "{color_code}" } in JSON)

By default, this key is #000000 (black).

Show exampleHide example

In this example, we configure a dynamic icon color from the data with a fallback to red.

cloudcannon.config.yaml

copied

preview:
  icon: edit_note
  icon_color:
    - key: color
    - '#ff0000'

cloudcannon.config.json

copied

{
  "preview": {
    "icon": "edit_note",
    "icon_color": [
      {
        "key": "color"
      },
      "#ff0000"
    ]
  }
}

In this example, we use a static icon color.

cloudcannon.config.yaml

copied

preview:
  icon: nature_people
  icon_color:
    - '#00ff00'

cloudcannon.config.json

copied

{
  "preview": {
    "icon": "nature_people",
    "icon_color": [
      "#00ff00"
    ]
  }
}

image — Array, or String#

Defines an image path to load over the icon.

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.

text — Array, or String#

Defines text to display in the centre of the gallery area if there is no icon or image.

icon — Array, String, or Boolean#

Defines an icon from Google’s Material Icons to display in the centre of the gallery area. match Material Icon name.

icon_color — Array, or String#

This key determines the color of the icon displayed on a Card.

This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:

A String of the exact value (e.g "#ff0000")
A reference to a key within the connected item (e.g key: color in YAML or { "key": "color" } in JSON)
A String with placeholders that will be replaced with values (e.g. template: {color_code} in YAML or { "template": "{color_code}" } in JSON)

By default, this key is #000000 (black).

Show exampleHide example

In this example, we configure a dynamic icon color from the data with a fallback to red.

cloudcannon.config.yaml

copied

preview:
  icon: edit_note
  icon_color:
    - key: color
    - '#ff0000'

cloudcannon.config.json

copied

{
  "preview": {
    "icon": "edit_note",
    "icon_color": [
      {
        "key": "color"
      },
      "#ff0000"
    ]
  }
}

In this example, we use a static icon color.

cloudcannon.config.yaml

copied

preview:
  icon: nature_people
  icon_color:
    - '#00ff00'

cloudcannon.config.json

copied

{
  "preview": {
    "icon": "nature_people",
    "icon_color": [
      "#00ff00"
    ]
  }
}

image — Array, or String#

Defines an image to display in the gallery area. Covers text and icon once the image is loaded.

fit — String#

Sets how image is displayed in the gallery. Must be cover (default) or contain.

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

copied

# String option
preview_option: Fallback String

# or, Array cascading option
preview_option:
- key: some_key
- key: object.subkey
- template: '{date|date_long}'
- Fallback String

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

copied

_type: figure
image_path: /image.png
alt_text: An image

When displaying this Figure we want to:

Always display the image icon (A String example)
In the text, display the image_path key falling back to the String ‘Image missing’ (An Array example)
In the subtext, display the alt_text key falling back to the String ‘No alternative text’ (Another Array example)

Writing this as a set of preview options will look like this:

copied

preview:
  icon: image
  text:
    - key: image_path
    - Image missing
  subtext:
    - key: alt_text
    - No alternative text

Template 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.

cloudcannon.config.yaml

copied

collections_config:
  posts:
    preview:
      metadata:
        - text:
            - template: By {author.name}
            - No author
          icon: person

cloudcannon.config.json

copied

{
  "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 subtext to prevent showing the String ‘No alternative text’

copied

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