API reference · picola

Lightbox is generic over your per-slide meta type: <Lightbox slides={...} /> infers T from the slides you pass.

Content

Prop	Type	Default	Description
`slides`	`Slide<T>[]`	—	Images to display (required).
`open`	`boolean`	`false`	Viewer visibility. Bindable.
`index`	`number`	`0`	Active slide index. Bindable — writing it while open navigates.

Behavior

Prop	Type	Default	Description
`zoom`	`ZoomOptions`	`{ max: 2, doubleTap: 2, wheel: true }`	Zoom limits, as multiples of natural size.
`dismiss`	`DismissOptions`	`{ drag: true, threshold: 0.22, pinch: true }`	Drag-to-dismiss and pinch-to-close.
`tapAction`	`'toggle-ui' \| 'close' \| 'none'`	`'toggle-ui'`	What a single tap on the image does.
`backdropClose`	`boolean`	`true`	Clicking outside the image closes the viewer.
`wheel`	`'zoom' \| 'navigate' \| 'none'`	`'zoom'`	Wheel behavior. Trackpad pinch always zooms.
`keyboard`	`boolean`	`true`	Handle Escape / arrows / `+` / `-`.
`history`	`boolean`	`false`	Push a history entry so the platform back gesture closes the viewer.
`loop`	`boolean`	`false`	Wrap past the ends. Seamless with 3+ slides; wrap-around below that.
`preload`	`readonly [number, number]`	`[1, 1]`	Slides kept mounted `[before, after]` the active one.

Appearance

Prop	Type	Default	Description
`chrome`	`boolean`	`true`	Render the built-in UI. Set `false` for a headless viewer.
`counter`	`boolean`	`true`	Show the `n / total` counter.
`zoomButton`	`boolean`	`true`	Show the zoom toggle button.
`showCaption`	`boolean`	`true`	Show the alt-text caption.
`backdropOpacity`	`number`	`0.9`	Backdrop opacity when fully open (`0`–`1`).
`slideGap`	`number`	`16`	Gap between adjacent slides, in px.
`transitionMs`	`number`	`260`	Open / close transition duration, in ms.
`labels`	`LightboxLabels`	—	Accessible labels for the built-in chrome (i18n).

Advanced

Prop	Type	Default	Description
`origin`	`(index: number) => HTMLElement \| OriginRect \| null`	—	Source element / rect for the open / close transition.
`container`	`HTMLElement`	`document.body`	Portal target for the viewer root.
`viewer`	`Viewer<T> \| null`	`null`	The core viewer instance while open. Bindable (`bind:viewer`).

Events

The most common events are exposed as callback props:

Prop	Payload	Fires when
`onopen`	`{ index }`	The opening transition starts.
`onchange`	`{ index, slide }`	The active slide changes.
`onload`	`{ index, slide }`	A slide’s full-quality image finishes decoding.
`onerror`	`{ index, slide, error }`	A slide’s full-quality image fails to load.
`onzoomintent`	`{ index, slide }`	The user first zooms a slide (once per slide).
`onclose`	`{ index }`	The closing transition starts.
`onclosed`	—	The closing transition finishes (safe to clean up).

For anything more, subscribe on the core viewer with viewer.on(name, listener) — see Framework-agnostic core for the full list of core events.

Snippets

Snippet	Argument
`toolbar`	`LightboxContext<T>`
`caption`	`LightboxContext<T> & { expanded: boolean; toggle(): void }`

Both receive a typed context:

Member	Type	Description
`viewer`	`Viewer<T>`	Core viewer, for advanced control.
`index`	`number`	Active slide index.
`slide`	`Slide<T> \| undefined`	Active slide (including your `meta`).
`count`	`number`	Total number of slides.
`close`	`() => void`	Close the viewer.
`next` / `prev`	`() => void`	Step to the adjacent slide.
`goTo`	`(index: number) => void`	Jump to a slide.
`updateSlide`	`(index, patch) => void`	Patch a slide in place.
`setKeyboardEnabled`	`(enabled: boolean) => void`	Suspend / resume key handling while your own modal is up.

Imperative control

Most control is declarative — bind:open, bind:index and a reactive slides array. For the rest, bind the component instance with bind:this:

<script lang="ts">
  import { Lightbox } from 'picola/svelte';
  let lightbox: Lightbox;
</script>

<Lightbox bind:this={lightbox} bind:open {slides} />
<button onclick={() => lightbox.next()}>Next</button>

Method	Description
`close()`	Start the close transition.
`next()` / `prev()`	Step to the adjacent slide.
`goTo(index)`	Navigate to a slide.
`updateSlide(index, patch)`	Patch a slide in place.
`getViewer()`	The core `Viewer` instance, or `null` when closed.

Slide type

Field	Type	Description
`src`	`string`	Full-quality image URL (required).
`placeholder`	`string`	Low-resolution stand-in shown instantly while `src` loads.
`width` / `height`	`number`	Natural pixel dimensions, if known ahead of time.
`alt`	`string`	Accessible description; also drives the caption.
`srcset` / `sizes`	`string`	Responsive candidates for `src`.
`meta`	`T`	Arbitrary per-slide data, fully typed via `Slide<T>`.

Accessible labels

The labels prop localises the built-in chrome. All fields are optional.

Field	Description
`dialog`	Accessible name of the viewer dialog.
`close`	Close button.
`next`	Next-slide arrow.
`prev`	Previous-slide arrow.
`zoom`	Zoom toggle button.
`caption`	Caption toggle button.

Exports

picola/svelte

Components — Lightbox, ToolbarButton
Helpers — createGalleryOrigins
Types — Slide, Viewer, SlideView, ViewerEvents, ViewerStatus, ZoomOptions, DismissOptions, TapAction, OriginRect, LightboxContext, LightboxLabels, GalleryOrigins

picola (core) — createViewer, Viewer, and the low-level primitives the adapter is built on (attachGestures, PanZoom, decodeImage, trapFocus, bindHistory, fitScale, panBounds, rubberBand, zoomAroundPoint), plus the full option and event types.

Lightbox props