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.

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)

Overview

When to use Thumbnail

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.

About Thumbnail

Thumbnail includes the following elements.

Image

The Thumbnail displays an image if one has been uploaded.

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

Placeholder icon

If the Thumbnail doesn't have an loaded image, it presents a placeholder gray icon against a light gray background.

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

Accessibility

In both scenarios, the Thumbnail features a @border-color-subtle border to ensure sufficient contrast when placed on @background-color-base backgrounds.

Size

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

Examples

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. Refer to the Card groups demo for an example.

Default placeholder

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

Custom placeholder icon

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>

Developer notes

To customize the placeholder icon, use the placeholderIcon prop.

Technical implementation

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