# Lightbox

A grid of thumbnails that opens one picture large. Each thumbnail is a plate with the picture set in it, and a real link to the full picture, so the grid works without any script. Press one and the page goes behind a near-black scrim. Left and Right turn the page, Home and End go to the first and the last, Escape puts it away, and on a touch screen a swipe does the same. It is dark in every finish, because a picture is looked at best in a dark room.

Kit part · With the Kit · https://tactileui.dev/parts/lightbox

> The code and styling for this part come with the Tactile UI Kit, which is in the Founder Pass. Sign in if you have it. Sign in: https://tactileui.dev/auth/sign-in The price: https://tactileui.dev/pricing

## Anatomy

The thumbnails are plates, as the kit draws them: the picture set in the plate with a hairline over its edge, so a pale picture on a pale page still has one. The viewer is the same native dialog as the drawer, full window, over a scrim made from the finish’s own shadow colour. The script is one dialog for each gallery, a dozen lines of keys, and a pointer handler for the swipe.

## Variants

- Nine pictures · 4:3 thumbnails
- Square thumbnails
- Tall thumbnails
- Open · the first picture · Previous is dimmed
- Open · a portrait picture
- Open · the last picture · Next is dimmed
- Open · a long caption wraps
- Open · narrow · the keys go under the picture
- A single picture · no arrows

## States

- Rest
- Hover
- Pressed
- Focused
- Loading

## Props and options

| Name | Kind | Description |
| - | - | - |
| [data-caption] | attribute | The caption printed under the large picture. Without one the alt text is what is said and the picture stands alone. |
| [data-src] | attribute | The large picture, when it is not the link’s address: on a button, or a link to a page. |
| openLightbox(gallery, index, opener) · closeLightbox() | function | Open a gallery at a picture, or put the viewer away, from your own code. |
| lightboxGridHTML() · lightboxHTML() | function | The gallery from a list of pictures, and the viewer showing one of them (as a dialog, or as a picture of it in a page). |
| lightboxKey() · lightboxSwipe() · lightboxSays() · lightboxCount() · lightboxItem() · lightboxClamp() | function | The picture a key goes to, what a swipe meant, the sentence said and the counter printed, a thumbnail’s picture, and the index kept in range. |

## Usage notes

Press a thumbnail: the viewer opens on it. Use Left and Right (or the keys either side) to turn the page, Home and End to go to the ends, and Escape to close; focus goes back to the thumbnail you opened it from. On a touch screen swipe sideways to turn the page, or down to close. The arrow at either end is dimmed and stays where it is: the pictures do not wrap round.

## Accessibility

- The page behind is inert, focus is held inside, Escape closes it, and focus goes back to the thumbnail that opened it. Focus starts on the close key, and the page does not scroll behind the viewer.
- Each thumbnail is a real link to the full picture with the picture’s alt text as its name, so the grid works, and reads as a list, without the script. The large picture has the same alt text, and it changes with the page.
- The printed counter is hidden from a screen reader so it is not read twice.
- Left and Right turn the page, and Home and End go to the first and the last. The pictures do not wrap. Under a right-to-left page the arrows swap.
- On a touch screen a swipe sideways turns the page and a swipe down closes; a short or slow drag sets the picture back. A mouse never drags.
- The room is dark in every finish, with the keys and the printing from that finish’s own dark tokens, so they read on black. The picture only moves by transform and opacity; under reduced motion the pictures swap with no slide and the viewer simply appears.

## Related parts

- [Carousel](https://tactileui.dev/parts/carousel): Slides seen one at a time through a viewer’s gate: transport keys either side of a frame counter on an LCD, lamp keys to jump, swipe on touch. Nothing moves on its own unless you ask it to.
- [Film strip](https://tactileui.dev/parts/film-strip): A carousel as a strip of film in a machined viewer. The frames run behind a gate lit from behind, with sprocket holes along both edges, and the frames either side wait under a smoked cover. It moves a frame at a time and settles as each one registers. Turn the thumbwheel, press the keys or swipe the film itself: underneath it is a native scroller with a snap point at every frame.
- [Drawer](https://tactileui.dev/parts/drawer): A panel that slides in from any edge of the window, on the native dialog. A face plate bolted to the frame, with a machined grip let into its inner edge to pull it shut by.
- [Aspect ratio](https://tactileui.dev/parts/aspect-ratio): A frame that holds one shape, whatever is put in it. Say the shape (16:9, 4:3, 1:1, 3:2, 21:9, 3:4) and the frame takes its height from its width; a picture, a video or a map inside it is cropped to fit, keeping the middle unless you say which part to keep. Until a picture arrives the frame is a recess, so the page does not jump. An optional hairline round the edge keeps a pale picture from dissolving into a pale page. Plain CSS, with no script.