Skip to content


A Thumbnail is a visual element used to display a small preview of an image. Thumbnails provide users with a quick glimpse of the associated content.


When to use thumbnails

Use the Thumbnail component to include small previews of images that can provide context or support the meaning of the content included in components such as Card or MenuItem.

The placeholder icon will display until the thumbnail image loads, or if a thumbnail image is not provided.


Specification of Thumbnail.

The thumbnail component may include the following elements:

  1. Image
    The thumbnail displays an image if one has been uploaded.
  2. Placeholder icon
    If the thumbnail doesn't have an loaded image, it presents a placeholder gray icon against a light gray background.

In both scenarios, the thumbnail features a Gray300 border to ensure sufficient contrast when placed on white backgrounds.

Component limitations

Thumbnails are set to a default square size of size-250 token (equivalent to 40px in the default Codex theme). They cannot be scaled smaller than this size but can be scaled up to @ize-800 (equivalent to 128px in the default Codex theme).

Refer to the Thumbnail component in Codex Figma.


There are two types of thumbnails based on whether an image has been loaded or not:

  1. Image
    If an image has been loaded, the thumbnail will display the image.
  2. Placeholder
    If no image has been loaded, the thumbnail will show a placeholder icon against a light gray background.

Types of Thumbnail: with image and with placeholder.

Interaction states

Thumbnail component just have two states:

Interaction states of Thumbnail: default and loading.

  1. Default: it will display the image if it is uploaded.
  2. Loading: it displays the placeholder view until the thumbnail image loads.

Best practices

Consider the following recommendations when using thumbnails.


Thumbnail within a Card.

  • Use Thumbnail as a preview of an image within other components such as Card or MenuItem.

Thumbnail within an InfoBox.

  • Replace images with Thumbnails, as Thumbnail is intended only as preview and an image should remain high-resolution.


Thumbnail using a customized simple icon.

  • Customize the icon within placeholder thumbnails.
  • Use icons that provide clear context for the use of the thumbnail.

Thumbnail using a customized complex icon.

  • Use icons that are difficult to understand or do not clearly convey their purpose.



Reading direction


The placeholder serves two purposes:

  1. To display while a thumbnail image is loading, improving the experience of those with slower connections
  2. To display when a thumbnail image is not provided

The second case may occur in a group of components, like Cards or MenuItems, when some items have a thumbnail image but some do not. In this case, the placeholder icon helps maintain a consistent layout for all items. See the MenuItem demo for an example.

Default placeholder

Custom placeholder icon

To customize the placeholder icon, use the placeholderIcon prop.

Vue usage


Prop nameDescriptionTypeDefault
thumbnailThumbnail data.Thumbnail|nullnull
placeholderIconThumbnail placeholder icon.IconcdxIconImageLayoutFrameless

CSS-only version

Markup structure

For the CSS-only version, a background-image rule must be set on the inner span. You can do this via a style attribute (like in the example below), or by adding a custom CSS class to the inner span and adding the background-image rule in your styles.


Default placeholder

To show the default placeholder icon, add two nested <span> elements inside the wrapper <span>:

  1. An outer <span> with the class cdx-thumbnail__placeholder
  2. An inner <span> with the class cdx-thumbnail__placeholder__icon

The default placeholder icon will automatically be added as a background image to the inner <span>.

Custom placeholder icon

To show a custom placeholder icon, add two nested <span> elements inside the wrapper <span>:

  1. An outer <span> with the class cdx-thumbnail__placeholder
  2. An inner <span> with your own custom CSS class

In your Less code, use your custom CSS class to add a CSS-only icon. Be sure to use @color-placeholder as the fill color.