ImageGallery | Tuff Docs

Usage

Basic

Clicking a thumbnail opens it in a fullscreen lightbox; startIndex picks the current preview image.

Loading demo...

Track Preview Opens

<script setup lang="ts">
function onOpen({ index, item }: { index: number, item: { id: string } }) {
  analytics.track('gallery_open', { index, imageId: item.id })
}
</script>

<template>
  <TxImageGallery :items="images" @open="onOpen" @close="onClose" />
</template>

Controlled Starting Image

startIndex only selects the preview index; it never opens the lightbox.

<template>
  <TxImageGallery :items="screenshots" :start-index="selectedIndex" />
</template>

Best Practices

Use stable id values, not array indexes, for long-lived gallery data.
Give informative images a name so button labels, alt text, and preview titles mean something.
Keep the list modest: every thumbnail renders, with no virtualization.
Normalize or proxy untrusted remote image URLs at your application boundary.
Don't mutate items synchronously in @open in a way that invalidates the opened image.

API Reference

Props

Prop	Type	Default	Description
`items`	`ImageGalleryItem[]`	required	Images shown as thumbnails and in the fullscreen preview.
`startIndex`	`number`	`0`	Current preview index, clamped to the item range.
`previousLabel`	`string`	`'Previous image'`	Accessible name of the previous button.
`nextLabel`	`string`	`'Next image'`	Accessible name of the next button.
`previousText`	`string`	`'Prev'`	Visible text of the previous button.
`nextText`	`string`	`'Next'`	Visible text of the next button.
`previewTitle`	`string`	`'Preview'`	Preview title when the current image has no `name`.
`itemLabelFormatter`	`(index: number) => string`	(i) => `Image ${i + 1}`	Builds a display name when `item.name` is absent.
`openLabelFormatter`	`(label: string) => string`	(label) => `Open ${label} preview`	Builds a thumbnail's `aria-label` from its display name.

Events

Event	Payload	Description
`open`	`{ index: number, item: ImageGalleryItem }`	Fires after a thumbnail opens the fullscreen preview.
`close`	`void`	Fires when the preview closes.

ImageGalleryItem

Field	Type	Description
`id`	`string`	Stable key for the thumbnail.
`url`	`string`	Image URL for the thumbnail and the preview.
`name`	`string`	Optional display name for labels, alt text, and the preview title.

Overview

Each thumbnail is a native <button type="button"> whose aria-label comes from openLabelFormatter.
Thumbnail and preview alt text is item.name; unnamed images deliberately get empty alt text.
The lightbox traps Tab focus, closes on Escape or the close button, and returns focus to the thumbnail that opened it.
Navigation is bounded: previous is disabled on the first image, next on the last; when a button disables, focus moves to the other.
The image is contained, never cropped, between the header and footer bars.
When items becomes empty, the preview closes and the index resets to 0.

Technologies

The lightbox is TxModal in fullscreen mode (teleported to body), not a separate overlay.
Source: packages/tuffex/packages/components/src/image-gallery/.

查看源码

packages/tuffex/packages/components/src/image-gallery/index.ts