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#

Prop	Type	Default	Description
`...props`	Base UI Dialog.Root props	—	Owns open state, modal behavior, Escape, pointer dismissal, and the optional Mod+W close helper.

LightboxTrigger#

Prop	Type	Default	Description
`...props`	Base UI Dialog.Trigger props	—	Opens the lightbox. Compose Button through render for visible triggers.

LightboxPortal#

Prop	Type	Default	Description
`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#

Prop	Type	Default	Description
`...props`	Base UI Dialog.Popup props	—	Renders Portal, Backdrop, and Popup. Defaults initialFocus/finalFocus to false for preview-like surfaces.

LightboxToolbar#

Prop	Type	Default	Description
`...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#

Prop	Type	Default	Description
`...props`	div props	—	In-flow header row for simpler shells (title + actions in document flow).

LightboxClose#

Prop	Type	Default	Description
`...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#

Prop	Type	Default	Description
`...props`	div props	—	Toolbar left cluster (gap 6px): preview-type chip then truncating filename.

LightboxHeaderLabel#

Prop	Type	Default	Description
`...props`	span props	—	Preview-type chip (or Badge) inside LightboxHeaderMeta.

LightboxMedia#

Prop	Type	Default	Description
`...props`	div props	—	Media frame for the stage photo. Borderless with a transparent background.

LightboxInfoDock#

Prop	Type	Default	Description
`...props`	div props	—	Absolute dock that centers LightboxInfoBar near the bottom of the stage.

LightboxActions#

Prop	Type	Default	Description
`...props`	div props	—	Toolbar right cluster (chip + buttons).

LightboxStage#

Prop	Type	Default	Description
`...props`	div props	—	Flex-1 preview surface under Toolbar or Header.

LightboxNavigationButton#

Prop	Type	Default	Description
`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#

Prop	Type	Default	Description
`...props`	div props	—	Bottom info bar centered by LightboxInfoDock.

LightboxInfoTitle#

Prop	Type	Default	Description
`...props`	useRender.ComponentProps<"div">	—	Truncating title used inside LightboxInfoDock.

LightboxInfoActions#

Prop	Type	Default	Description
`...props`	useRender.ComponentProps<"div">	—	Action row inside LightboxInfoDock for caller-owned actions.

LightboxThumbnailStrip#

Prop	Type	Default	Description
`...props`	div props	—	Absolute strip that centers LightboxThumbnail controls along the bottom of the stage.

LightboxThumbnail#

Prop	Type	Default	Description
`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#

Prop	Type	Default	Description
`...props`	div props	—	Truncating title slot, usually filename or preview label.