Image

WARNING

This component is still under development. It is not yet available in releases of Codex.

An Image is a visual element used to display content in various formats and states, supporting features like aspect ratios, placeholders, and responsive sizing.

<cdx-image />

Name	Value
Props
src
alt
aspectRatio	16-9 3-2 4-3 1-1 3-4 2-3
objectFit	fill contain cover none scale-down
objectPosition	top bottom left right center
position	left center right
width
height
View
Reading direction	Left to right (LTR) Right to left (RTL)

Overview

When to use Image

Use the Image component to display visual content like photos or illustrations that enhance context and meaning. Ideal for adding visual elements in layouts, supporting text content, or embedding in components like cards and dialogs. Avoid using for purely decorative purposes or stylized visual elements. Always include meaningful alt text for accessibility.

Examples

Default

NPM

<template>
	<cdx-image
		:src="imageData.url"
		:alt="imageData.alt"
		:width="imageData.width"
		:height="imageData.height"
		:position="imageData.position"
	/>
</template>

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

const imageData = {
	url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/f/f7/003_Olive-bellied_Sunbird_in_flight_at_Kibale_forest_National_Park_Photo_by_Giles_Laurent.jpg/2560px-003_Olive-bellied_Sunbird_in_flight_at_Kibale_forest_National_Park_Photo_by_Giles_Laurent.jpg',
	alt: 'Olive-bellied Sunbird flying from a flower to another at Kibale forest National Park',
	width: 400,
	height: 220
};

export default defineComponent( {
	name: 'ImageDefault',
	components: { CdxImage },
	setup() {
		return {
			imageData
		};
	}
} );
</script>

MediaWiki

<template>
	<cdx-image
		:src="imageData.url"
		:alt="imageData.alt"
		:width="imageData.width"
		:height="imageData.height"
		:position="imageData.position"
	></cdx-image>
</template>

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

const imageData = {
	url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/f/f7/003_Olive-bellied_Sunbird_in_flight_at_Kibale_forest_National_Park_Photo_by_Giles_Laurent.jpg/2560px-003_Olive-bellied_Sunbird_in_flight_at_Kibale_forest_National_Park_Photo_by_Giles_Laurent.jpg',
	alt: 'Olive-bellied Sunbird flying from a flower to another at Kibale forest National Park',
	width: 400,
	height: 220
};

module.exports = defineComponent( {
	name: 'ImageDefault',
	components: { CdxImage },
	setup() {
		return {
			imageData
		};
	}
} );
</script>

Aspect Ratio

NPM

<template>
	<cdx-image
		:src="imageData.url"
		:alt="imageData.alt"
		:aspect-ratio="aspectRatio"
		:object-fit="objectFit"
		:width="imageData.width"
		:height="imageData.height"
	/>
</template>

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

const imageData = {
	url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/f/f7/003_Olive-bellied_Sunbird_in_flight_at_Kibale_forest_National_Park_Photo_by_Giles_Laurent.jpg/2560px-003_Olive-bellied_Sunbird_in_flight_at_Kibale_forest_National_Park_Photo_by_Giles_Laurent.jpg',
	alt: 'An example image with aspect ratio 16:9',
	width: 400,
	height: 220
};

const aspectRatio = '3-4';
const objectFit = 'cover';

export default defineComponent( {
	name: 'ImageAspectRatio',
	components: { CdxImage },
	setup() {
		return {
			imageData,
			aspectRatio,
			objectFit
		};
	}
} );
</script>

MediaWiki

<template>
	<cdx-image
		:src="imageData.url"
		:alt="imageData.alt"
		:aspect-ratio="aspectRatio"
		:object-fit="objectFit"
		:width="imageData.width"
		:height="imageData.height"
	></cdx-image>
</template>

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

const imageData = {
	url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/f/f7/003_Olive-bellied_Sunbird_in_flight_at_Kibale_forest_National_Park_Photo_by_Giles_Laurent.jpg/2560px-003_Olive-bellied_Sunbird_in_flight_at_Kibale_forest_National_Park_Photo_by_Giles_Laurent.jpg',
	alt: 'An example image with aspect ratio 16:9',
	width: 400,
	height: 220
};

const aspectRatio = '3-4';
const objectFit = 'cover';

module.exports = defineComponent( {
	name: 'ImageAspectRatio',
	components: { CdxImage },
	setup() {
		return {
			imageData,
			aspectRatio,
			objectFit
		};
	}
} );
</script>

Placeholder

NPM

<template>
	<cdx-image
		:src="imageData.url"
		:alt="imageData.alt"
		:width="imageData.width"
		:height="imageData.height"
	/>
</template>

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

const imageData = {
	url: '',
	alt: 'This is an example of an image placeholder',
	width: 400,
	height: 220
};

export default defineComponent( {
	name: 'ImagePlaceholder',
	components: { CdxImage },
	setup() {
		return {
			imageData
		};
	}
} );
</script>

MediaWiki

<template>
	<cdx-image
		:src="imageData.url"
		:alt="imageData.alt"
		:width="imageData.width"
		:height="imageData.height"
	></cdx-image>
</template>

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

const imageData = {
	url: '',
	alt: 'This is an example of an image placeholder',
	width: 400,
	height: 220
};

module.exports = defineComponent( {
	name: 'ImagePlaceholder',
	components: { CdxImage },
	setup() {
		return {
			imageData
		};
	}
} );
</script>

Error

NPM

<template>
	<cdx-image
		:src="imageData.url"
		:alt="imageData.alt"
		:width="imageData.width"
		:height="imageData.height"
	/>
</template>

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

const imageData = {
	url: 'https://invalid-url.example.com/nonexistent-image.jpg',
	alt: 'This is an example of an image error state',
	width: 400,
	height: 220
};

export default defineComponent( {
	name: 'ImageError',
	components: { CdxImage },
	setup() {
		return {
			imageData
		};
	}
} );
</script>

MediaWiki

<template>
	<cdx-image
		:src="imageData.url"
		:alt="imageData.alt"
		:width="imageData.width"
		:height="imageData.height"
	></cdx-image>
</template>

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

const imageData = {
	url: 'https://invalid-url.example.com/nonexistent-image.jpg',
	alt: 'This is an example of an image error state',
	width: 400,
	height: 220
};

module.exports = defineComponent( {
	name: 'ImageError',
	components: { CdxImage },
	setup() {
		return {
			imageData
		};
	}
} );
</script>

Technical implementation

Vue usage

Props

Prop name	Description	Type	Values	Default
src	The source URL of the image.	string	-	''
alt(required)	Alternative text for the image. Descriptive text must be provided unless the image is decorative or described elsewhere.	string	-	''
aspectRatio	The aspect ratio of the image. Accepts one of the predefined aspect ratios.	ImageAspectRatio	-	null
objectPosition	The object-position of the image when cropping with an aspect ratio. Accepts 'top', 'bottom', 'left', 'right', or 'center'.	typeof ObjectPositions[number]	-	'center'
objectFit	Specifies how the image should be resized to fit its container. Accepts 'fill', 'contain', 'cover', 'none', or 'scale-down'.	typeof ObjectFitOptions[number]	-	'cover'
position	Image position on a page	string	left, center, right	''
width	The width of the image in pixels.	string|number	-	undefined
height	The height of the image in pixels.	string|number	-	undefined
loadingPriority	The loading priority of the image. Accepts 'lazy' or 'eager'.	string	lazy, eager	'lazy'

Events

Event name	Properties	Description
error	event Event - The error event object.	Emitted when an error occurs loading the image.