Thumbnail ​

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.

Guidelines ​

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

Specifications ​

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.

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.

Types ​

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.

Interaction states ​

Thumbnail component just have two states:

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.

Usage ​

Icon ​

Demos ​

Default ​

<template>
	<cdx-thumbnail :thumbnail="thumbnailData" />
</template>

<script>
import { defineComponent } from 'vue';
import { CdxThumbnail } from '@wikimedia/codex';

const thumbnailData = {
	width: 200,
	height: 150,
	url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/2/21/64_365_Color_Macro_%285498808099%29.jpg/200px-64_365_Color_Macro_%285498808099%29.jpg'
};

export default defineComponent( {
	name: 'ThumbnailDefault',
	components: { CdxThumbnail },
	setup() {
		return {
			thumbnailData
		};
	}
} );
</script>

<template>
	<cdx-thumbnail :thumbnail="thumbnailData"></cdx-thumbnail>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxThumbnail } = require( '@wikimedia/codex' );

const thumbnailData = {
	width: 200,
	height: 150,
	url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/2/21/64_365_Color_Macro_%285498808099%29.jpg/200px-64_365_Color_Macro_%285498808099%29.jpg'
};

// @vue/component
module.exports = defineComponent( {
	name: 'ThumbnailDefault',
	components: { CdxThumbnail },
	setup() {
		return {
			thumbnailData
		};
	}
} );
</script>

Reading direction

Placeholder ​

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 ​

<cdx-thumbnail :thumbnail="null" />

Custom placeholder icon ​

To customize the placeholder icon, use the placeholderIcon prop.

<template>
	<cdx-thumbnail :thumbnail="null" :placeholder-icon="cdxIconArticle" />
</template>

<script>
import { defineComponent } from 'vue';
import { CdxThumbnail } from '@wikimedia/codex';
import { cdxIconArticle } from '@wikimedia/codex-icons';

export default defineComponent( {
	name: 'ThumbnailCustomIcon',
	components: { CdxThumbnail },
	setup() {
		return {
			cdxIconArticle
		};
	}
} );
</script>

<template>
	<cdx-thumbnail :thumbnail="null" :placeholder-icon="cdxIconArticle"></cdx-thumbnail>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxThumbnail } = require( '@wikimedia/codex' );
const { cdxIconArticle } = require( './icons.json' );

// @vue/component
module.exports = defineComponent( {
	name: 'ThumbnailCustomIcon',
	components: { CdxThumbnail },
	setup() {
		return {
			cdxIconArticle
		};
	}
} );
</script>

Vue usage ​

Props ​

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.

<!-- Wrapper <span>. -->
<span class="cdx-thumbnail">
  <!-- Image span. -->
  <span
    class="cdx-thumbnail__image"
    style="background-image: url( https://upload.wikimedia.org/wikipedia/commons/thumb/2/21/64_365_Color_Macro_%285498808099%29.jpg/200px-64_365_Color_Macro_%285498808099%29.jpg );"
  ></span>
</span>

Placeholder ​

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

<span class="cdx-thumbnail">
  <span class="cdx-thumbnail__placeholder">
    <span class="cdx-thumbnail__placeholder__icon"></span>
  </span>
</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.

<span class="cdx-thumbnail">
  <span class="cdx-thumbnail__placeholder">
    <span class="cdx-demo-css-icon--article"></span>
  </span>
</span>

// Note: you must import the design tokens before importing the css-icon mixin
@import (reference) "@wikimedia/codex-design-tokens/theme-wikimedia-ui.less";
@import (reference) "@wikimedia/codex/mixins/css-icon.less";

.cdx-demo-css-icon--article {
  .cdx-mixin-css-icon( @cdx-icon-article, @color-placeholder );
}

@import "mediawiki.skin.variables.less";

.cdx-demo-css-icon--article {
  .cdx-mixin-css-icon( @cdx-icon-article, @color-placeholder );
}