Lightbox

A full-screen preview surface for image, screenshot, and attachment review.

Preview#

Anatomy#

import {
  Lightbox,
  LightboxClose,
  LightboxContent,
  LightboxInfoActions,
  LightboxInfoBar,
  LightboxInfoDock,
  LightboxInfoTitle,
  LightboxMedia,
  LightboxNavigationButton,
  LightboxStage,
  LightboxThumbnail,
  LightboxThumbnailStrip,
  LightboxTitle,
  LightboxTrigger,
} from "raft-ui";

<Lightbox>
  <LightboxTrigger />
  <LightboxContent>
    <LightboxTitle />
    <LightboxClose />
    <LightboxStage>
      <LightboxNavigationButton direction="previous" />
      <LightboxNavigationButton direction="next" />
      <LightboxMedia />
      <LightboxInfoDock>
        <LightboxInfoBar>
          <LightboxInfoTitle />
          <LightboxInfoActions />
        </LightboxInfoBar>
      </LightboxInfoDock>
      <LightboxThumbnailStrip>
        <LightboxThumbnail />
      </LightboxThumbnailStrip>
    </LightboxStage>
  </LightboxContent>
</Lightbox>

Usage#

Image shell#

Attachment shell#

API#WIP

Lightbox#

...props
Base UI Dialog.Root props
Owns open state, modal behavior, Escape, pointer dismissal, and the optional Mod+W close helper.

LightboxTrigger#

...props
Base UI Dialog.Trigger props
Opens the lightbox. Compose Button through render for visible triggers.

LightboxPortal#

container
HTMLElement | RefObject | null
Custom portal container for framed previews or contained overlays.
...props
Dialog.Portal.Props
Portals the lightbox to the body or a custom container.

LightboxContent#

...props
Base UI Dialog.Popup props
Renders Portal, Backdrop, and Popup. Defaults initialFocus/finalFocus to false for preview-like surfaces.

LightboxToolbar#

...props
div props
Attachment header: left LightboxHeaderMeta + right LightboxActions. Owns in-flow button layout so Close is not treated as the image-shell floating control.

LightboxHeader#

...props
div props
In-flow header row for simpler shells (title + actions in document flow).

LightboxClose#

...props
Base UI Dialog.Close props
Close control. Direct child of LightboxContent → floating top-right (image shell). Inside LightboxToolbar → in-flow with the action buttons.

LightboxHeaderMeta#

...props
div props
Toolbar left cluster (gap 6px): preview-type chip then truncating filename.

LightboxHeaderLabel#

...props
span props
Preview-type chip (or Badge) inside LightboxHeaderMeta.

LightboxMedia#

...props
div props
Media frame for the stage photo. Borderless with a transparent background.

LightboxInfoDock#

...props
div props
Absolute dock that centers LightboxInfoBar near the bottom of the stage.

LightboxActions#

...props
div props
Toolbar right cluster (chip + buttons).

LightboxStage#

...props
div props
Flex-1 preview surface under Toolbar or Header.

LightboxNavigationButton#

direction
"next" | "previous"
Chooses the previous or next affordance for multi-item preview navigation.
disabled
boolean
Disables the control and blocks click handling.
...props
ButtonProps (size/variant/loading omitted)
Button attributes for the navigation control.

LightboxInfoBar#

...props
div props
Bottom info bar centered by LightboxInfoDock.

LightboxInfoTitle#

...props
useRender.ComponentProps<"div">
Truncating title used inside LightboxInfoDock.

LightboxInfoActions#

...props
useRender.ComponentProps<"div">
Action row inside LightboxInfoDock for caller-owned actions.

LightboxThumbnailStrip#

...props
div props
Absolute strip that centers LightboxThumbnail controls along the bottom of the stage.

LightboxThumbnail#

active
boolean
Marks the current thumbnail and updates border/overlay chrome.
...props
button props
Thumbnail control. Put the preview image in children; selection state stays caller-owned.

LightboxTitle#

...props
div props
Truncating title slot, usually filename or preview label.