Lightbox

A dedicated full-screen modal component designed for focused media display.

styleKeys: lightbox

Lightbox is only available in the React API for SWAN. This component requires internationalisation (i18n) to be set up in your application.

UsageGuidelinesAPI

Use Lightbox...

To provide a full-screen, distraction-free environment for inspecting media content (such as images, carousels, or videos).
In flows where a small image preview needs to open into a larger, more detailed, immersive view

Don’t use Lightbox...

When you need to show non‑media or mixed content (for example, long text, forms, or layouts where images are just one part of the UI), use ModalDialog instead.
When the content would not benefit from a full‑screen, immersive, media‑first presentation.

Trigger

With Zoomable Image

Use ZoomableImage as the trigger to open the image in a Lightbox when you want to provide a second level of zoom for detailed inspection at higher magnification.

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  return (
    <>
      <Box style={{ width: '400px' }}>
        <ZoomableImage
          src="/example-images/1x1-6.webp"
          onExpandClick={() => setIsOpen(true)}
        />
      </Box>
      <Lightbox
        aria-label="Product image"
        isOpen={isOpen}
        onRequestDismiss={() => setIsOpen(false)}
      >
        <ZoomableImage src="/example-images/1x1-6.webp" />
      </Lightbox>
    </>
  )
}

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  return (
    <>
      <Box style={{ width: '400px' }}>
        <ZoomableImage
          src="/example-images/1x1-6.webp"
          onExpandClick={() => setIsOpen(true)}
        />
      </Box>
      <Lightbox
        aria-label="Product image"
        isOpen={isOpen}
        onRequestDismiss={() => setIsOpen(false)}
      >
        <ZoomableImage src="/example-images/1x1-6.webp" />
      </Lightbox>
    </>
  )
}

With Adaptive Carousel

Use ZoomableImage inside the Adaptive carousel as the trigger to open the same Adaptive carousel in a Lightbox, providing a second level of zoom for detailed, high‑magnification inspection.

To keep the active slide in sync between the page carousel and the Lightbox carousel, pass the active slide number into the Lightbox carousel via the initialSlide prop. This ensures the Lightbox opens on the same active slide on which the user triggers the Lightbox.

When an Adaptive Carousel is rendered inside a Lightbox, the Lightbox enforces a single-slide view and disables Slide Picker Thumbnails to maintain a distraction-free, full-screen experience.

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  const [activeSlide, setActiveSlide] = React.useState(null)

  const handleSlideChange = slide => {
    setActiveSlide(slide)
  }

  return (
    <Box style={{ width: '400px' }}>
      <AdaptiveCarousel
        aria-label="Carousel"
        slidesToShow={1}
        onSlideChange={handleSlideChange}
      >
        <AdaptiveCarouselSlide>
          <ZoomableImage
            src="/example-images/1x1-6.webp"
            onExpandClick={() => setIsOpen(true)}
          />
        </AdaptiveCarouselSlide>
        <AdaptiveCarouselSlide>
          <ZoomableImage
            src="/example-images/1x1-6.webp"
            onExpandClick={() => setIsOpen(true)}
          />
        </AdaptiveCarouselSlide>
        <AdaptiveCarouselSlide>
          <ZoomableImage
            src="/example-images/1x1-6.webp"
            onExpandClick={() => setIsOpen(true)}
          />
        </AdaptiveCarouselSlide>
      </AdaptiveCarousel>

      <Lightbox
        aria-label="Product gallery"
        isOpen={isOpen}
        onRequestDismiss={() => setIsOpen(false)}
      >
        <AdaptiveCarousel aria-label="Carousel" initialSlide={activeSlide}>
          <AdaptiveCarouselSlide>
            <ZoomableImage src="/example-images/1x1-6.webp" />
          </AdaptiveCarouselSlide>
          <AdaptiveCarouselSlide>
            <ZoomableImage src="/example-images/1x1-6.webp" />
          </AdaptiveCarouselSlide>
          <AdaptiveCarouselSlide>
            <ZoomableImage src="/example-images/1x1-6.webp" />
          </AdaptiveCarouselSlide>
        </AdaptiveCarousel>
      </Lightbox>
    </Box>
  )
}

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  const [activeSlide, setActiveSlide] = React.useState(null)

  const handleSlideChange = slide => {
    setActiveSlide(slide)
  }

  return (
    <Box style={{ width: '400px' }}>
      <AdaptiveCarousel
        aria-label="Carousel"
        slidesToShow={1}
        onSlideChange={handleSlideChange}
      >
        <AdaptiveCarouselSlide>
          <ZoomableImage
            src="/example-images/1x1-6.webp"
            onExpandClick={() => setIsOpen(true)}
          />
        </AdaptiveCarouselSlide>
        <AdaptiveCarouselSlide>
          <ZoomableImage
            src="/example-images/1x1-6.webp"
            onExpandClick={() => setIsOpen(true)}
          />
        </AdaptiveCarouselSlide>
        <AdaptiveCarouselSlide>
          <ZoomableImage
            src="/example-images/1x1-6.webp"
            onExpandClick={() => setIsOpen(true)}
          />
        </AdaptiveCarouselSlide>
      </AdaptiveCarousel>

      <Lightbox
        aria-label="Product gallery"
        isOpen={isOpen}
        onRequestDismiss={() => setIsOpen(false)}
      >
        <AdaptiveCarousel aria-label="Carousel" initialSlide={activeSlide}>
          <AdaptiveCarouselSlide>
            <ZoomableImage src="/example-images/1x1-6.webp" />
          </AdaptiveCarouselSlide>
          <AdaptiveCarouselSlide>
            <ZoomableImage src="/example-images/1x1-6.webp" />
          </AdaptiveCarouselSlide>
          <AdaptiveCarouselSlide>
            <ZoomableImage src="/example-images/1x1-6.webp" />
          </AdaptiveCarouselSlide>
        </AdaptiveCarousel>
      </Lightbox>
    </Box>
  )
}

With External Trigger

When you want the Lightbox to be opened by a control that is separate from the image itself, or you can’t use the image (or carousel slide) as a clear, tappable trigger (for example, because it’s too small), use an external trigger instead. In these cases, provide a separate, clearly identifiable control to open the Lightbox.

Use an IconButton with an “expand” icon placed near the media to provide a clear, accessible trigger for the full-screen view.

Maintain consistency by using "Expand" as the default tooltip, or provide more context for specific images with labels like "Expand business card image."

() => {
  const [isOpen, setIsOpen] = React.useState(false)

  return (
    <>
      <FlexBox
        flexDirection="column"
        alignItems="center"
        gap={5}
        style={{ width: '150px' }}
      >
        <FluidImage src="/example-images/1x1-5.webp" />
        <IconButton tooltip="Expand" onClick={() => setIsOpen(true)}>
          <Icon iconType="expand" />
        </IconButton>
      </FlexBox>
      <Lightbox
        aria-label="Product image"
        isOpen={isOpen}
        onRequestDismiss={() => setIsOpen(false)}
      >
        <ZoomableImage src="/example-images/1x1-5.webp" />
      </Lightbox>
    </>
  )
}

() => {
  const [isOpen, setIsOpen] = React.useState(false)

  return (
    <>
      <FlexBox
        flexDirection="column"
        alignItems="center"
        gap={5}
        style={{ width: '150px' }}
      >
        <FluidImage src="/example-images/1x1-5.webp" />
        <IconButton tooltip="Expand" onClick={() => setIsOpen(true)}>
          <Icon iconType="expand" />
        </IconButton>
      </FlexBox>
      <Lightbox
        aria-label="Product image"
        isOpen={isOpen}
        onRequestDismiss={() => setIsOpen(false)}
      >
        <ZoomableImage src="/example-images/1x1-5.webp" />
      </Lightbox>
    </>
  )
}

Accessibility

Use the aria-label prop to provide a descriptive name for the Lightbox (e.g., "Product Image Gallery").

Content

When opening a Lightbox from an AdaptiveCarousel, keep the active slide in sync. The Lightbox should open on the same slide the user selected in the main carousel to preserve context and continuity.

Complexity and flow

Avoid nested modal dialog. Do not open additional modals from within a Lightbox.

Props

Lightbox

This component is implemented using the <dialog /> as the root element. You can utilize the native attributes supported by <dialog /> tag.

See core props for additional props that can be applied to this component.

prop	type	required	description	default
onRequestDismiss	`() => void`	true	Callback function which will be invoked when the modal wants to be dismissed.	null
isOpen	`boolean \| null`	false	Show/hide dialog	false
takeOver	`boolean \| null`	false	Decide whether to fill the full screen.	false
onlyRenderWhenOpen	`boolean \| null`	false	only renders the contents of the dialog if the modal is open this is different than native dialog behavior, where the content is rendered but hidden	false

Lightbox

Use Lightbox...

Don’t use Lightbox...

Trigger

With Zoomable Image

With Adaptive Carousel

With External Trigger

Accessibility

Content

Complexity and flow

Props

Related