---
name: gallery-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit Gallery for
product or media image galleries with Carousel integration, thumbnails,
controlled page, orientation, thumbnail image adapters, thumbnail aria labels,
empty state, and NextImage support.
metadata:
component_version: "1.2.1"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux carousel-usage framework-consumer-integration app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: ""
contributor_sources: "libs/ui/src/organisms/gallery.tsx libs/ui/src/tokens/components/organisms/_gallery.css libs/ui/stories/organisms/gallery.stories.tsx"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit Gallery Usage
Use Gallery for product or media galleries with thumbnails. Use Carousel
directly when thumbnails are not part of the UX.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `Gallery`.
**Use it when**
- Product detail images with thumbnails and variant switching. Gallery has no zoom or fullscreen view; don't promise either in copy or icons.
**Use something else when**
| Need | Use instead |
| --- | --- |
| Banners or related items without thumbnails | Carousel |
| Single image | Image |
| Media management in admin | a media library grid |
**Do**
- Keep a fixed aspect ratio so the page doesn't jump between images.
- Give every image meaningful alt text (product, colour, angle); thumbnails can share the main alt.
- Switch the gallery when the user changes the colour variant.
- Support keyboard and swipe; show position (`2 / 6`).
**Don't**
- Auto-rotate product images.
- Hide the only view of a variant behind the 10th thumbnail.
**Copy and states**
- Alt text: `Linen shirt in navy, front`; controls `Previous image`, `Next image`.
**Behaviour (from the UX spec)**
- The selected thumbnail and the main image always show the same view; never link one variant's thumbnail to another variant's image.
- Every thumbnail stays reachable however many there are. A missing image is a neutral placeholder, never another variant's photo.
- The default thumbnail name is English `Show slide N`; pass a localized `getThumbnailAriaLabel` that names the view and position.
**Figma → code**
| Figma | Code |
| --- | --- |
| `orientation=vertical` / `horizontal` | `orientation` (default `vertical`) |
| — | `showThumbnails`, `hideThumbnailsWhenSingle`, `thumbnailSize`, `emptyState` (code only) |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Organisms/Gallery → UX guidelines*.
## Setup
```tsx
import NextImage from "next/image"
import { Gallery } from "@techsio/ui-kit/organisms/gallery"
```
Supported props:
```text
items: GalleryItem[]
orientation: horizontal | vertical
value/defaultValue, onValueChange
showThumbnails, hideThumbnailsWhenSingle, thumbnailSize
thumbnailImageAs, getThumbnailAriaLabel, carouselProps, emptyState
parts: Main, Thumbnails, Thumbnail, Carousel, Slides
```
## Core Patterns
### Use Gallery for thumbnail UX
It coordinates active page state between thumbnails and Carousel.
### Use NextImage adapters in Next apps
Pass `thumbnailImageAs={NextImage}` and `carouselProps.imageAs`.
### Keep thumbnail labels meaningful
Override `getThumbnailAriaLabel` when "Show slide N" is not enough.
## Common Mistakes
### HIGH Custom thumbnail state
Wrong:
```tsx
{items.map((item, i) =>