Image

Display images and explore galleries.

Basic usage

basic.tsx

import { Flex, Image } from '@ifhover/leaf-ui';

import { withBase } from '@rspress/core/runtime';

export function ImageBasic() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Image src={withBase('/media/landscape-1.svg')} width={240} height={160} alt="Green valley" />
      <Image
        src="data:image/png;base64,invalid"
        width={140}
        height={160}
        alt="Failed image example"
        fallback={<span>No image</span>}
      />
    </Flex>
  );
}

More examples

advanced.tsx

import { Flex, Image, ImagePreviewGroup } from '@ifhover/leaf-ui';

import { withBase } from '@rspress/core/runtime';

export function ImageGallery() {
  return (
    <ImagePreviewGroup thumbnails downloadable>
      <Flex gap="md" align="center" wrap justify="center">
        {[1, 2, 3].map((index) => (
          <Image
            key={index}
            src={withBase(`/media/landscape-${index}.svg`)}
            width={180}
            height={120}
            alt={`Landscape ${index}`}
          />
        ))}
      </Flex>
    </ImagePreviewGroup>
  );
}

Usage

Supports keyboard navigation, touch swiping, zoom, thumbnails and fullscreen. ImagePreviewGroup collects child Images or accepts items and controlled open / index. Use preview={false} for display-only images.

Types

Import these types for data, callbacks and refs.

import type { ImagePreviewGroupProps, ImagePreviewItem, ImagePreviewProps, ImageProps } from '@ifhover/leaf-ui';

ImagePreviewGroupProps API

Property	Type	Default	Description
`children`	`ReactNode`	—	Content or child items
`items`	`readonly ImagePreviewItem[]`	—	Images in display order
`open`	`boolean`	—	Controlled visibility
`defaultOpen`	`boolean`	`false`	Initial visibility
`onOpenChange`	`(open: boolean) => void`	—	Open state changes
`index`	`number`	—	Current index, starting at zero
`defaultIndex`	`number`	`0`	Initial index
`onIndexChange`	`(index: number) => void`	—	Active image changes
`thumbnails`	`boolean`	`true`	Thumbnail navigation
`downloadable`	`boolean`	`false`	Show download action

ImagePreviewItem API

Property	Type	Default	Description
`src`	`string`	Required	Image URL
`thumbnailSrc`	`string`	—	Optional thumbnail URL; falls back to src
`alt`	`string`	`''`	Image description
`width`	`number`	—	Width, numbers are in pixels
`height`	`number`	—	Height, numbers are in pixels
`download`	`string \| boolean`	—	Download URL, or whether downloads are allowed
`downloadName`	`string`	—	Optional filename for the downloaded image

ImagePreviewProps API

Property	Type	Default	Description
`items`	`readonly ImagePreviewItem[]`	Required	Images in display order
`open`	`boolean`	Required	Controlled visibility
`index`	`number`	`0`	Current index, starting at zero
`onClose`	`() => void`	Required	Called when closed
`onIndexChange`	`(index: number) => void`	—	Active image changes
`thumbnails`	`boolean`	`true`	Thumbnail navigation
`downloadable`	`boolean`	`false`	Show download action

ImageProps API

Property	Type	Default	Description
`preview`	`boolean`	`true`	Allow enlarged preview
`previewSrc`	`string`	—	Higher-resolution preview URL
`fallback`	`ReactNode`	—	Loading error content
`fit`	`'cover' \| 'contain' \| 'fill' \| 'none' \| 'scale-down'`	`'cover'`	Image fitting mode

Image supports native image attributes such as src, alt, width, height, loading, onLoad and onError.

#Image

#Basic usage

#More examples

#Usage

#Types

#ImagePreviewGroupProps API

#ImagePreviewItem API

#ImagePreviewProps API

#ImageProps API