🌏 Translated with the assistance of DeepSeek and ChatGPT

Image

As the name suggests, displays an image.

The example images in this document are from Lorem Picsum.

Basic Usage

You can set src, srcset, and alt, and use it just like the <img> tag.

<template>
	<px-image
		src="https://picsum.photos/id/106/200/100"
		srcset="https://picsum.photos/id/106/400/200 2x, https://picsum.photos/id/106/600/300 3x"
		alt="Image"
		style="width: 200px; height: 100px"
	></px-image>
</template>

Fit to Container

The objectFit property sets how the image fits its container, similar to the CSS object-fit.

<template>
	<px-space>
		<px-image
			v-for="value in objectFit"
			src="https://picsum.photos/id/106/200/100"
			alt="Image"
			:object-fit="value"
			style="width: 100px; height: 100px"
		></px-image>
	</px-space>
</template>

<script setup lang="ts">
const objectFit = ['fill', 'contain', 'cover', 'none', 'scale-down']
</script>

Placeholder and Load Failure

placeholder and error respectively set the content displayed while loading and when loading fails.

Loading...

<template>
	<px-space style="font-size: 0">
		<px-image
			src="https://picsum.photos/id/106/200/100"
			alt="Image"
			style="width: 200px; height: 100px"
		>
			<template #placeholder> Loading... </template>
		</px-image>
		<px-image src="error-url" alt="Image" style="width: 200px; height: 100px">
			<template #error> Error! </template>
		</px-image>
	</px-space>
</template>

Lazy Loading

The loading property enables native browser image lazy loading. lazy enables lazy loading based on IntersectionObserver, and the root property sets the visible area for lazy loading.

To prevent reflow and reduce page jitter, it is recommended to set the image size when using lazy loading.

Loading Prop

Lazy Prop

<template>
	<px-space>
		<div>
			<h4>Loading Prop</h4>
			<div class="lazy-container-left">
				<px-image
					v-for="value in 10"
					:key="value"
					src="https://picsum.photos/id/106/200/100"
					alt="Image"
					style="width: 100%; height: 100px"
					loading="lazy"
				></px-image>
			</div>
		</div>
		<div>
			<h4>Lazy Prop</h4>
			<div class="lazy-container-right">
				<px-image
					v-for="value in 10"
					:key="value"
					src="https://picsum.photos/id/106/200/100"
					alt="Image"
					style="width: 100%; height: 100px"
					lazy
					root=".lazy-container-righ"
				></px-image>
			</div>
		</div>
	</px-space>
</template>

<style lang="css" scoped>
.lazy-container-left,
.lazy-container-right {
	width: 200px;
	height: 500px;
	font-size: 0;
	overflow: auto;
}
</style>

Preview

Enable large image preview with previewable. The preview image size is calculated based on the image resource dimensions.

<template>
	<px-image
		src="https://picsum.photos/id/106/600/300"
		alt="Image"
		previewable
		style="width: 200px; height: 100px"
	></px-image>
</template>

API

ImageProps

Attribute	Type	Optional	Default	Description	Version
src	string	True		Image resource URL, behaves like the native <img> src.	0.0.3
srcset	string	True		Responsive image resource URL, behaves like the native <img> srcset.	0.0.3
alt	string	True		Same as the native <img> alt.	0.0.3
objectFit	'fill' | 'contain' | 'cover' | 'none' | 'scale-down'	True	'fill'	How the image fits its container, same as CSS object-fit.	0.0.3
loading	'eager' | 'lazy'	True	'eager'	Native image lazy loading.	0.0.3
lazy	boolean	True	false	Image lazy loading. When enabled, the loading property will be disabled. This property is not reactive.	0.0.3
root	HTMLElement | string	True		For image lazy loading based on the lazy property, sets the visible area element. If empty, defaults to the viewport. This property is not reactive.	0.0.3
rootMargin	number | [number, number]	True	[100, 200]	For image lazy loading based on the lazy property, sets the distance from the visible area. This property is not reactive.	0.0.3
previewable	boolean	True	false	Whether to enable large image preview.	0.0.3
maskProps	Omit<MaskProps, 'zIndex'>	True		Properties for the mask during preview.	0.0.3
popupWrapperProps	{ zIndex: number, root: HTMLElement | string }	True		Properties for the floating layer during preview.	0.0.3
popupWrapperProps	{ maxWidth?: number, maxHeight?: number, margin?: number}	True	{ margin: 32, maxWidth: Infinity, maxHeight: Infinity }	Properties for the floating layer during preview.	0.0.3
referrerpolicy	string	True	'no-referrer'	Same as the native <img> referrerpolicy.	0.0.3
crossorigin	'anonymous' | 'use-credentials' | ''	True	''	Same as the native <img> crossorigin.	0.0.3

ImageEvents

Event	Parameter	Description	Version
load	img: HTMLImageElement, event: Event	Callback when the image loads successfully.	0.0.3
error	img: HTMLImageElement, error: string | Event	Callback when the image fails to load.	0.0.3
loading	img: HTMLImageElement	Callback when the image starts loading with the lazy property.	0.0.3
preview	event: MouseEvent	Callback when previewing the image.	0.0.3
close	event: MouseEvent	Callback when closing the image preview.	0.0.3

ImageSlots

Slot	Parameter	Description	Version
placeholder		Placeholder element while loading.	0.0.3
error		Content displayed when loading fails.	0.0.3