Lightbox

Use Lightbox when an image needs an inspectable full-size view. It expands from the thumbnail and returns to that same origin when dismissed.

Preview

Reduce motion:Off

Tune:Off

Inspect

Installation

Base UI Motion

npx shadcn@latest add @sona-ui/lightbox

Basic usage

project-image.tsx

import Lightbox from "@/components/ui/lightbox/lightbox";
 
export function ProjectImage() {
return <Lightbox src="/project.jpg" alt="Project overview" />;
}

Examples

Use controlled open state when the selected image is managed by a gallery. Add a caption when it provides information that is not visible in the image itself.

Usage


export default function LightboxDemo() {
  return (
    <Lightbox
      alt="Accordion component preview on a dark canvas"
      caption="Select the backdrop, close button, or press Escape to return."
      className="aspect-[16/10] w-full max-w-xl"
      src="/og/accordion-og.png"
    />
  );
}

API

Property	Type	Default	Description
`src`	`string`	`required`	The image URL shown in both the thumbnail and expanded preview.
`alt`	`string`	`required`	Accessible alternative text for the image.
`caption`	`string`	`undefined`	Optional caption displayed beneath the expanded image.
`open`	`boolean`	`undefined`	Controlled open state.
`defaultOpen`	`boolean`	`false`	Initial open state for uncontrolled usage.
`onOpenChange`	`(open: boolean) => void`	`undefined`	Called whenever the expanded preview opens or closes.
`className`	`string`	`undefined`	Additional CSS classes for the thumbnail trigger.
`imageClassName`	`string`	`undefined`	Additional CSS classes for the thumbnail image.
`previewClassName`	`string`	`undefined`	Additional CSS classes for the expanded image.
`backdropClassName`	`string`	`undefined`	Additional CSS classes for the modal backdrop.

Accessibility

Lightbox manages focus, Escape dismissal, and scroll locking through Base UI. Always provide useful alternative text for the image.

Styling

Use the thumbnail, preview, and backdrop class options to match the gallery. Reduced-motion preferences use a cross-fade.

Contact

Found a bug or need help using this component? Open an issue on GitHub.

License & Usage

Sona UI is available under the MIT license. You may use, modify, and distribute this component in personal and commercial projects.

Was this page helpful?

Your response helps us improve component docs.