API reference

• State
  RootcreateHandle
• Trigger / Item
  TriggerItemMedia
• Layout
  SlidesSlide
• View transitions
  Root (VT props)Document (VT)
• Shell
  PortalBackdropContent
• Gestures
  ContentZoomZoomInZoomOut
• Chrome
  ClosePreviousNextCounterCaptionThumbnailGroupThumbnailThumbnailStripThumbnailStripTrack

Groups all parts of the lightbox and owns open state, active index, the view transition morph and the active zoom bridge. Renders no element of its own. Pass handle from createHandle() for imperative control and detached Triggers, or call show(index) and close() on the instance from bind:this. Prefer onOpenChangeComplete for work after the motion; use scrollTriggerIntoView so close morphs land on screen when the page scrolled while open.

A <button> that opens the lightbox at a given index and is the morph source. Carries the dialog trigger semantics: aria-haspopup="dialog", aria-controls pointing at the dialog while open, and aria-expanded set only on the trigger that opened it. Pass handle to use it outside Root. Prefer the snippet form of children to attach imageRef / morphRef.

Moves Backdrop and Content into a host element (default document.body). Pass container and keepMounted here. With keepMounted, give the Portal host a stacking level yourself (e.g. class="relative z-[1]").

Optional scrim (place inside Lightbox.Portal, typically beside Content). Click closes the lightbox. Tracks pull to dismiss progress.

Dialog surface (role="dialog", aria-modal). Provide an accessible name through aria-label or aria-labelledby (the library warns in development when it is missing). Place inside Lightbox.Portal. Owns focus trap, Escape, scroll lock and pull to dismiss; a click on the surface itself (not its children) closes. When Lightbox.Stage is mounted, arrow, Home and End navigation, zoom shortcuts (unmodified +, -, 0) and pull are scoped to Stage; otherwise Content is the stage. Arrow keys pan instead of navigate while the active Zoom is above 1×.

Optional media interaction surface inside Content. Scopes pull to dismiss, Zoom pan viewport geometry, arrow, Home and End navigation, and zoom shortcuts to the media pane. Place side panels as siblings of Stage under Content. When omitted, Content itself is the stage. Attach morphRef from the snippet when the morph should capture this surface (or a descendant) instead of the active item.

Default layout: horizontal snap carousel wired to the active index. Emits role="group"; pass a translated aria-roledescription="carousel" plus an aria-label or aria-labelledby naming the gallery. Gates Item contents through preload; put Slide, Item, Zoom and Media inside. While zoomed or pulling, the scroller is locked so gestures do not fight the scroll.

One snap aligned slide box inside Slides. Snap alignment is built in and the default box is full width (flex: 0 0 100%); override flex, width or min-width through class or style for other layouts. Place a Lightbox.Item (and typically Zoom and Media) inside. Put resting chrome and safe area insets as padding on Slide so Item and Zoom fill the content box.

A single lightbox item. Registers its caption and morph and placeholder refs. ARIA adapts: it is a tabpanel wired to its Lightbox.Thumbnail tab when a ThumbnailGroup is present, otherwise role="group", which needs a translated aria-roledescription="slide" and an aria-label carrying the position from you. Inactive items are inert. Prefer nesting Lightbox.Media around the destination <img> or <video>. Outside Slides every item renders its content; inside Slides, preload gates it.

Pinch, wheel, double click and keyboard zoom and pan surface. Fills its host and is a CSS size container for nested Media. Does not clip; clipping belongs on Content or chrome so zoomed media can escape the resting box. Prefer Zoom, then Media, then img or video. Publishes to the Root’s active zoom bridge so ZoomIn and ZoomOut in toolbar chrome target the active slide. Methods are on the instance from bind:this (see Zoom instance).

Sized destination media host: morph target and placeholder canvas container. width and height give it a fit box; direct img and video children fill it. Cosmetics (radius, colors, object-fit) stay yours. Prefer Zoom, then Media, then img or video. Reads the size of the first <img> or <video> when width and height are omitted.

Button that closes the lightbox. Ships no label: give it visible text or pass aria-label / aria-labelledby in your language (the library warns in development when it is nameless).

Navigate to the previous item. Disabled at the start when loop is false.

Navigate to the next item. Disabled at the end when loop is false.

Increments zoom. Works inside Zoom, or as global chrome through the active slide zoom bridge.

Decrements zoom. Works inside Zoom, or as global chrome through the active slide zoom bridge.

Shows the active position (e.g. "1 / 12") in an aria-live region.

Renders the active item’s caption from the Item caption registry, in an aria-live region.

Accessible tablist of thumbnails with arrow, Home and End keyboard support. Without a ThumbnailStrip, the active thumbnail scrolls itself to the center of its parent.

A single thumbnail tab that activates the given index.

Scroll linked thumbnail strip root. Always centers the active thumbnail on the midline (Photos style) and follows the Slides scroll position. Compose with ThumbnailStripTrack and Thumbnails. Discrete navigation (thumbnail pointer, keyboard, Previous / Next) scrubs the track with an animation; a pointer pick also runs an element scoped view transition on Slides. Flex, gap and thumbnail size stay consumer CSS.

Linked tablist track for ThumbnailStrip: a ThumbnailGroup that the strip moves (same keyboard and ARIA). The parent ThumbnailStrip writes the travel variable and the transform; flex, gap and thumbnail sizing are consumer CSS.

Provides the Content Security Policy nonce for the <style> tag ramka inserts. Wrap it around everything that renders lightbox parts, including detached Triggers outside any Root, and pass the same per request nonce your server puts in the style-src directive. When the browser still refuses the tag, the library falls back to a constructed stylesheet.

While a morph runs, ramka sets attributes on <html> and CSS variables on ::view-transition so you can style the ::view-transition-* pseudo elements. Cleared when the transition finishes.

Helper types you will see in callbacks and snippets, exported on the Lightbox namespace (Lightbox.NavigationSource and so on):

• NavigationSource: 'trigger' | 'keyboard' | 'thumbnail' | 'button' | 'scroll' | 'imperative'. Second argument to Root onValueChange. Handle open/goTo use 'imperative'; scroll-driven Slides use 'scroll'.
• Crossfade: 'open' | 'close' | 'both' for Trigger crossfade. See View transitions: crossfade.
• MorphTo: 'active' | 'origin' | 'closest' for Root morphTo, and MorphPreset: 'default' | 'snappy' | 'relaxed' | 'spring' for Root viewTransition.
• Snippet state types such as TriggerContext and ItemContext (active, visible, refs) are documented on Trigger / Item.

Context getters for nested wrapper components, the Svelte form of the React hooks. Call them during component initialization inside the matching part.

Reads the enclosing Root’s state during component initialisation. Use it to build custom chrome that reads or drives the lightbox. Throws outside a Root.

Context from the enclosing Trigger. Use it in nested wrappers (e.g. a shared TriggerImage component) to attach imageRef / morphRef without threading the snippet argument. Returns null outside a Trigger.

Context from the enclosing Item. Use it in nested wrappers to attach imageRef / morphRef or read active and index. Prefer Lightbox.Media for the common morph and placeholder host. Returns null outside an Item.

Context from the enclosing Stage. Use it in nested wrappers to attach morphRef without threading the snippet argument. Returns null outside a Stage.

Context from the enclosing Media. Use it in nested wrappers that need the morph and placeholder host element. Returns null outside a Media.

Use Lightbox.createHandle() on Root (and optional detached Triggers). Zoom exposes its controls through bind:this.

Imperative handle from createHandle(). Pass it to Root (and to detached Triggers). Calls before the Root mounts do nothing.

State and methods on the Zoom component instance from bind:this. The getters are reactive.