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

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.

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.

Component limitations

Thumbnails have a minimum width and height of size-250 (equivalent to 40px in the default Codex theme). A larger thumbnail size can be specified using CSS if desired (the Card component uses size-300 for its Thumbnail dimensions, for example).

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

Do:

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

Don't:

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

Icon

Do:

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

Don't:

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

Demos

Default

NPM

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

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

const thumbnailData = {
	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>

MediaWiki

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

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

const thumbnailData = {
	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'
};

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

Name	Value
View
Reading direction	Left to right (LTR) Right to left (RTL)

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.

NPM

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

MediaWiki

<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' );

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

Vue usage

Props

Prop name	Description	Type	Default
thumbnail	Thumbnail data.	Thumbnail|null	null
placeholderIcon	Thumbnail placeholder icon.	Icon	cdxIconImageLayoutFrameless

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>

NPM

// 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 );
}

MediaWiki

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

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