--- 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) =>