> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/image.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# Image

Display images and explore galleries.

## Basic usage


![Green valley](/leaf-ui/media/landscape-1.svg)![Failed image example](data:image/png;base64,invalid)

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/image/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>
  );
}
```

Expand code

## More examples


![Landscape 1](/leaf-ui/media/landscape-1.svg)![Landscape 2](/leaf-ui/media/landscape-2.svg)![Landscape 3](/leaf-ui/media/landscape-3.svg)

advanced.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/image/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>
  );
}
```

Expand code

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

```ts
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[]`](#imagepreviewitem-api) | —       | 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[]`](#imagepreviewitem-api) | 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.