Image Viewer

1.32.0 Alpha

Image Viewer renders a static image preview and opens a full-screen viewer for pan, zoom, rotation, and flip interactions.

import {ImageViewer} from "@qualcomm-ui/react/image-viewer"

Keyboard and Pointer Interactions

Focus the full-screen viewport to use keyboard interactions.

Arrow keys pan the image by nudgeStep, which defaults to 1 pixel.
Shift with an Arrow key uses nudgeStepShift, which defaults to 10 pixels.
Ctrl or Cmd with an Arrow key uses nudgeStepCtrl, which defaults to 50 pixels.
+ or = zooms in.
- or _ zooms out.
The mouse wheel zooms around the pointer position.
Pinch gestures zoom and pan the image on touch devices.
Press Escape or click the backdrop to close the viewer.

Closing resets zoom, rotation, flip, and pan.

Examples

Simple

Use src and alt to render an image preview with the default popup, zoom, and reset controls.

<ImageViewer
  alt="Scenic view of a lake in the mountains"
  src="/images/nature-2.avif"
/>

Composite

Supply src and alt to <ImageViewer.Root>, then provide the composite parts to render the viewer.

import type {ReactElement} from "react"

import {ButtonGroup} from "@qualcomm-ui/react/button"
import {ImageViewer} from "@qualcomm-ui/react/image-viewer"

export function ImageViewerCompositeDemo(): ReactElement {
  return (
    <ImageViewer.Root
      alt="Scenic view of a lake in the mountains"
      className="w-full"
      src="/images/nature-2.avif"
    >
      <ImageViewer.Trigger className="block w-full">
        <ImageViewer.StaticImage className="mx-auto block max-w-full" />
      </ImageViewer.Trigger>
      <ImageViewer.FloatingPortal>
        <ImageViewer.CloseButton />
        <ImageViewer.Viewport>
          <ImageViewer.ViewportImage />
        </ImageViewer.Viewport>
        <ButtonGroup aria-label="Image controls" size="sm">
          <ImageViewer.ZoomOutButton />
          <ImageViewer.ZoomInButton />
          <ImageViewer.ResetButton />
        </ButtonGroup>
      </ImageViewer.FloatingPortal>
    </ImageViewer.Root>
  )
}

Controlled Open State

Use open and onOpenChange for controlled popup visibility. These props follow our controlled state pattern.

import {useState, type ReactElement} from "react"

import {ImageViewer} from "@qualcomm-ui/react/image-viewer"

export function ImageViewerControlledOpenDemo(): ReactElement {
  const [open, setOpen] = useState(false)

  return (
    <ImageViewer
      alt="Scenic view of a lake in the mountains"
      className="w-full"
      onOpenChange={setOpen}
      open={open}
      src="/images/nature-2.avif"
    />
  )
}

Controlled Zoom

Set zoom and update it in onZoomChange. These props follow our controlled state pattern.

1.0x

import {type ReactElement, useState} from "react"

import {ImageViewer} from "@qualcomm-ui/react/image-viewer"

export function ImageViewerControlledZoomDemo(): ReactElement {
  const [zoom, setZoom] = useState(1)

  return (
    <div className="flex w-full flex-col items-center gap-4">
      <ImageViewer
        alt="Scenic view of a lake in the mountains"
        className="w-full"
        onZoomChange={(details) => setZoom(details.zoom)}
        src="/images/nature-2.avif"
        zoom={zoom}
      />
      <output>{zoom.toFixed(1)}x</output>
    </div>
  )
}

Zoom Limits

Set minZoom and maxZoom to constrain the zoom range.

1.0x

Zoom is limited to 0.5x through 2x.

import {type ReactElement, useState} from "react"

import {ImageViewer} from "@qualcomm-ui/react/image-viewer"

const minZoom = 0.5
const maxZoom = 2

export function ImageViewerZoomLimitsDemo(): ReactElement {
  const [zoom, setZoom] = useState(1)

  return (
    <div className="flex w-full flex-col items-center gap-4">
      <ImageViewer
        alt="Scenic view of a lake in the mountains"
        className="w-full"
        maxZoom={maxZoom}
        minZoom={minZoom}
        onZoomChange={(details) => setZoom(details.zoom)}
        src="/images/nature-2.avif"
        zoom={zoom}
      />
      <output>{zoom.toFixed(1)}x</output>
      <p className="text-body-sm text-neutral-secondary">
        Zoom is limited to {minZoom}x through {maxZoom}x.
      </p>
    </div>
  )
}

Rotation

Set rotation and update it in onRotationChange. These props follow our controlled state pattern.

import {type ReactElement, useState} from "react"

import {RotateCcw, RotateCw} from "lucide-react"

import {ButtonGroup, IconButton} from "@qualcomm-ui/react/button"
import {ImageViewer} from "@qualcomm-ui/react/image-viewer"

export function ImageViewerRotationDemo(): ReactElement {
  const [rotation, setRotation] = useState(0)

  return (
    <div className="flex w-full flex-col items-center gap-4">
      <ImageViewer.Root
        alt="Scenic view of a lake in the mountains"
        className="w-full"
        onRotationChange={(details) => setRotation(details.rotation)}
        rotation={rotation}
        src="/images/nature-2.avif"
      >
        <ImageViewer.Trigger className="block w-full">
          <ImageViewer.StaticImage className="mx-auto block max-w-full" />
        </ImageViewer.Trigger>
        <ImageViewer.FloatingPortal>
          <ImageViewer.CloseButton />
          <ImageViewer.Viewport>
            <ImageViewer.ViewportImage />
          </ImageViewer.Viewport>
          <div className="flex items-center gap-2">
            <ButtonGroup
              aria-label="Rotation controls"
              emphasis="white-persistent"
              size="sm"
              variant="outline"
            >
              <IconButton
                aria-label="Rotate counter-clockwise"
                icon={RotateCcw}
                onClick={() =>
                  setRotation((currentRotation) => currentRotation - 90)
                }
              />
              <IconButton
                aria-label="Rotate clockwise"
                icon={RotateCw}
                onClick={() =>
                  setRotation((currentRotation) => currentRotation + 90)
                }
              />
            </ButtonGroup>
            <output>{rotation}°</output>
          </div>
        </ImageViewer.FloatingPortal>
      </ImageViewer.Root>
    </div>
  )
}

Flip

Set flip and update it in onFlipChange. These props follow our controlled state pattern.

import {type ReactElement, useState} from "react"

import {FlipHorizontal, FlipVertical} from "lucide-react"

import {ButtonGroup, IconButton} from "@qualcomm-ui/react/button"
import {ImageViewer} from "@qualcomm-ui/react/image-viewer"

export function ImageViewerFlipDemo(): ReactElement {
  const [flip, setFlip] = useState({horizontal: false, vertical: false})

  return (
    <div className="flex w-full flex-col items-center gap-4">
      <ImageViewer.Root
        alt="Scenic view of a lake in the mountains"
        className="w-full"
        flip={flip}
        onFlipChange={(details) => setFlip(details.flip)}
        src="/images/nature-2.avif"
      >
        <ImageViewer.Trigger className="block w-full">
          <ImageViewer.StaticImage className="mx-auto block max-w-full" />
        </ImageViewer.Trigger>
        <ImageViewer.FloatingPortal>
          <ImageViewer.CloseButton />
          <ImageViewer.Viewport>
            <ImageViewer.ViewportImage />
          </ImageViewer.Viewport>
          <ButtonGroup
            aria-label="Flip controls"
            emphasis="white-persistent"
            size="sm"
          >
            <IconButton
              aria-label="Flip horizontally"
              emphasis="white-persistent"
              icon={FlipHorizontal}
              onClick={() =>
                setFlip((currentFlip) => ({
                  ...currentFlip,
                  horizontal: !currentFlip.horizontal,
                }))
              }
              variant={flip.horizontal ? "fill" : "outline"}
            />
            <IconButton
              aria-label="Flip vertically"
              icon={FlipVertical}
              onClick={() =>
                setFlip((currentFlip) => ({
                  ...currentFlip,
                  vertical: !currentFlip.vertical,
                }))
              }
              variant={flip.vertical ? "fill" : "outline"}
            />
          </ButtonGroup>
        </ImageViewer.FloatingPortal>
      </ImageViewer.Root>
    </div>
  )
}

Reset

Use useImageViewer with <RootProvider> when external code owns the viewer state and popup composition.

import type {ReactElement} from "react"

import {
  FlipHorizontal,
  RefreshCw,
  RotateCcw,
  RotateCw,
  ZoomIn,
  ZoomOut,
} from "lucide-react"

import {useImageViewer} from "@qualcomm-ui/react-core/image-viewer"
import {ButtonGroup, IconButton} from "@qualcomm-ui/react/button"
import {ImageViewer} from "@qualcomm-ui/react/image-viewer"

export function ImageViewerResetDemo(): ReactElement {
  const imageViewer = useImageViewer()

  return (
    <ImageViewer.RootProvider
      alt="Scenic view of a lake in the mountains"
      className="w-full"
      src="/images/nature-2.avif"
      value={imageViewer}
    >
      <ImageViewer.Trigger className="block w-full">
        <ImageViewer.StaticImage className="mx-auto block max-w-full" />
      </ImageViewer.Trigger>
      <ImageViewer.FloatingPortal>
        <ImageViewer.CloseButton />
        <ImageViewer.Viewport>
          <ImageViewer.ViewportImage />
        </ImageViewer.Viewport>
        <ButtonGroup
          aria-label="Image controls"
          emphasis="white-persistent"
          size="sm"
          variant="outline"
        >
          <IconButton
            aria-label="Zoom out"
            icon={ZoomOut}
            onClick={() => imageViewer.zoomBy(-0.1)}
          />
          <IconButton
            aria-label="Zoom in"
            icon={ZoomIn}
            onClick={() => imageViewer.zoomBy(0.1)}
          />
          <IconButton
            aria-label="Rotate counter-clockwise"
            icon={RotateCcw}
            onClick={() => imageViewer.rotateBy(-90)}
          />
          <IconButton
            aria-label="Rotate clockwise"
            icon={RotateCw}
            onClick={() => imageViewer.rotateBy(90)}
          />
          <IconButton
            aria-label="Flip horizontally"
            icon={FlipHorizontal}
            onClick={() => imageViewer.flipHorizontally()}
          />
          <IconButton
            aria-label="Reset image"
            icon={RefreshCw}
            onClick={() => imageViewer.reset()}
          />
        </ButtonGroup>
      </ImageViewer.FloatingPortal>
    </ImageViewer.RootProvider>
  )
}

Events

Use onZoomChange to track the current zoom level.

Current zoom: 1.00x

import {type ReactElement, useState} from "react"

import {ImageViewer} from "@qualcomm-ui/react/image-viewer"

export function ImageViewerEventsDemo(): ReactElement {
  const [zoom, setZoom] = useState(1)

  return (
    <div className="flex w-full flex-col gap-4">
      <ImageViewer
        alt="Scenic view of a lake in the mountains"
        className="w-full"
        onZoomChange={(details) => setZoom(details.zoom)}
        src="/images/nature-2.avif"
      />
      <output>Current zoom: {zoom.toFixed(2)}x</output>
    </div>
  )
}

Context

Use <ImageViewer.Context> to access the viewer API inside the root.

import type {ReactElement} from "react"

import {ZoomIn, ZoomOut} from "lucide-react"

import {ButtonGroup, IconButton} from "@qualcomm-ui/react/button"
import {ImageViewer} from "@qualcomm-ui/react/image-viewer"

export function ImageViewerContextDemo(): ReactElement {
  return (
    <ImageViewer.Root
      alt="Scenic view of a lake in the mountains"
      className="w-full"
      src="/images/nature-2.avif"
    >
      <ImageViewer.Trigger className="block w-full">
        <ImageViewer.StaticImage className="mx-auto block max-w-full" />
      </ImageViewer.Trigger>
      <ImageViewer.FloatingPortal>
        <ImageViewer.CloseButton />
        <ImageViewer.Viewport>
          <ImageViewer.ViewportImage />
        </ImageViewer.Viewport>
        <ImageViewer.Context>
          {(context) => (
            <div className="flex items-center justify-center gap-2">
              <ButtonGroup
                aria-label="Zoom controls"
                emphasis="white-persistent"
                size="sm"
                variant="outline"
              >
                <IconButton
                  aria-label="Zoom out"
                  icon={ZoomOut}
                  onClick={() => context.zoomBy(-0.1)}
                />
                <IconButton
                  aria-label="Zoom in"
                  icon={ZoomIn}
                  onClick={() => context.zoomBy(0.1)}
                />
              </ButtonGroup>
              <output>{context.zoom.toFixed(1)}x</output>
            </div>
          )}
        </ImageViewer.Context>
      </ImageViewer.FloatingPortal>
    </ImageViewer.Root>
  )
}

Root Provider

Use useImageViewer with <ImageViewer.RootProvider> when external code owns the viewer API.

import type {ReactElement} from "react"

import {ZoomIn, ZoomOut} from "lucide-react"

import {useImageViewer} from "@qualcomm-ui/react-core/image-viewer"
import {ButtonGroup, IconButton} from "@qualcomm-ui/react/button"
import {ImageViewer} from "@qualcomm-ui/react/image-viewer"

export function ImageViewerRootProviderDemo(): ReactElement {
  const imageViewer = useImageViewer()

  return (
    <ImageViewer.RootProvider
      alt="Scenic view of a lake in the mountains"
      className="w-full"
      src="/images/nature-2.avif"
      value={imageViewer}
    >
      <ImageViewer.Trigger className="block w-full">
        <ImageViewer.StaticImage className="mx-auto block max-w-full" />
      </ImageViewer.Trigger>
      <ImageViewer.FloatingPortal>
        <ImageViewer.CloseButton />
        <ImageViewer.Viewport>
          <ImageViewer.ViewportImage />
        </ImageViewer.Viewport>
        <div className="flex items-center justify-center gap-2">
          <ButtonGroup
            aria-label="Zoom controls"
            emphasis="white-persistent"
            size="sm"
            variant="outline"
          >
            <IconButton
              aria-label="Zoom out"
              icon={ZoomOut}
              onClick={() => imageViewer.setZoom(imageViewer.zoom - 0.1)}
            />
            <IconButton
              aria-label="Zoom in"
              icon={ZoomIn}
              onClick={() => imageViewer.setZoom(imageViewer.zoom + 0.1)}
            />
          </ButtonGroup>
          <output>{imageViewer.zoom.toFixed(1)}x</output>
        </div>
      </ImageViewer.FloatingPortal>
    </ImageViewer.RootProvider>
  )
}

API

<ImageViewer>

The simple API accepts the props from ImageViewer.Root except children. It renders the preview, popup, zoom controls, and reset control. Use the composite API for custom popup contents.

Displays an image preview that opens a popup with zoom and reset controls.

Prop	Type
children The simple ImageViewer doesn't support children.	never
closeButtonProps Props applied to the close button.	ImageViewerCloseButtonProps
controlsProps Props applied to the button group containing the zoom and reset controls.	ButtonGroupProps
floatingPortalProps Props applied to the portal, backdrop, positioner, and popup content.	ImageViewerFloatingPortalProps
resetButtonProps Props applied to the reset button.	ImageViewerResetButtonProps
staticImageProps Props applied to the static preview image. Its src and alt default to the root values.	ImageViewerStaticImageProps
triggerProps Props applied to the preview button that opens the popup.	ImageViewerTriggerProps
viewportImageProps Props applied to the expanded image. Its src and alt default to the root values.	ImageViewerViewportImageProps
viewportProps Props applied to the pan and zoom viewport.	ImageViewerViewportProps
zoomInButtonProps Props applied to the zoom in button.	ImageViewerZoomInButtonProps
zoomOutButtonProps Props applied to the zoom out button.	ImageViewerZoomOutButtonProps

children

Type

never

Description

The simple ImageViewer doesn't support children.

closeButtonProps

Type

ImageViewerCloseButtonProps

Description

Props applied to the close button.

controlsProps

Type

ButtonGroupProps

Description

Props applied to the button group containing the zoom and reset controls.

floatingPortalProps

Type

ImageViewerFloatingPortalProps

Description

Props applied to the portal, backdrop, positioner, and popup content.

resetButtonProps

Type

ImageViewerResetButtonProps

Description

Props applied to the reset button.

staticImageProps

Type

ImageViewerStaticImageProps

Description

Props applied to the static preview image. Its src and alt default to the root values.

triggerProps

Type

ImageViewerTriggerProps

Description

Props applied to the preview button that opens the popup.

viewportImageProps

Type

ImageViewerViewportImageProps

Description

Props applied to the expanded image. Its src and alt default to the root values.

viewportProps

Type

ImageViewerViewportProps

Description

Props applied to the pan and zoom viewport.

zoomInButtonProps

Type

ImageViewerZoomInButtonProps

Description

Props applied to the zoom in button.

zoomOutButtonProps

Type

ImageViewerZoomOutButtonProps

Description

Props applied to the zoom out button.

ImageViewerApi

The viewer API is available from <ImageViewer.Context> and useImageViewer.

Use open and setOpen to read and update popup visibility when external code owns the viewer API.

Prop	Type
flip The current flip state of the image.	{ horizontal: boolean vertical: boolean }
flipHorizontally Function to flip the image horizontally. Pass a boolean to set explicitly or omit to toggle.	( value?: boolean, ) => void
flipVertically Function to flip the image vertically. Pass a boolean to set explicitly or omit to toggle.	( value?: boolean, ) => void
getRootElement Resolves the inline root for portal placement.	() => HTMLElement
getRootNode Resolves the document or shadow root that owns the viewer.	() => \| Node \| ShadowRoot \| Document
getViewportElement Resolves the interactive viewport for popup focus management.	() => HTMLElement
measureViewport Measures the mounted viewport after its aspect ratio has been applied.	() => void
naturalSize The natural (original) size of the image.	{ height: number width: number }
offset The current offset (pan position) of the image.	{ x: number y: number }
open Whether the popup is open.	boolean
panning Whether the image is currently being panned.	boolean
ready Whether the expanded image is loaded and its viewport has been measured.	boolean
reset Function to reset the viewer to its initial state.	() => void
rotateBy Function to rotate the image by a relative amount in degrees.	( degrees: number, ) => void

rotation The current rotation of the image in degrees.	number
setFlip Function to set the flip state of the image.	( flip: Partial<{ horizontal: boolean vertical: boolean }>, ) => void
setImageStatus Updates the mounted image's natural dimensions and loading status.	(status: { ready: boolean size: { height: number width: number } }) => void
setOpen Requests a popup open state change. Closing restores the initial transform.	( open: boolean, ) => void
setRotation Function to set the rotation of the image.	( rotation: number, ) => void
setZoom Function to set the zoom level of the image.	( zoom: number, ) => void
translations Localized labels for the popup controls.	{ listLabel?: string }
viewportRect The viewport rectangle dimensions and position.	{ bottom: number height: number left: number right: number top: number width: number }
zoom The current zoom level of the image.	number
zoomBy Function to zoom the image by a relative amount.	( delta: number, ) => void

flip

Type

{
  horizontal: boolean
  vertical: boolean
}

Description

The current flip state of the image.

flipHorizontally

Type

(
  value?: boolean,
) => void

Description

Function to flip the image horizontally. Pass a boolean to set explicitly or omit to toggle.

flipVertically

Type

(
  value?: boolean,
) => void

Description

Function to flip the image vertically. Pass a boolean to set explicitly or omit to toggle.

getRootElement

Type

() => HTMLElement

Description

Resolves the inline root for portal placement.

getRootNode

Type

() =>
| Node
| ShadowRoot
| Document

Description

Resolves the document or shadow root that owns the viewer.

getViewportElement

Type

() => HTMLElement

Description

Resolves the interactive viewport for popup focus management.

measureViewport

Type

() => void

Description

Measures the mounted viewport after its aspect ratio has been applied.

naturalSize

Type

{
  height: number
  width: number
}

Description

The natural (original) size of the image.

offset

Type

{
  x: number
  y: number
}

Description

The current offset (pan position) of the image.

open

Type

boolean

Description

Whether the popup is open.

panning

Type

boolean

Description

Whether the image is currently being panned.

ready

Type

boolean

Description

Whether the expanded image is loaded and its viewport has been measured.

reset

Type

() => void

Description

Function to reset the viewer to its initial state.

rotateBy

Type

(
  degrees: number,
) => void

Description

Function to rotate the image by a relative amount in degrees.

rotation

Type

number

Description

The current rotation of the image in degrees.

setFlip

Type

(
  flip: Partial<{
    horizontal: boolean
    vertical: boolean
  }>,
) => void

Description

Function to set the flip state of the image.

setImageStatus

Type

(status: {
  ready: boolean
  size: {
    height: number
    width: number
  }
}) => void

Description

Updates the mounted image's natural dimensions and loading status.

setOpen

Type

(
  open: boolean,
) => void

Description

Requests a popup open state change. Closing restores the initial transform.

setRotation

Type

(
  rotation: number,
) => void

Description

Function to set the rotation of the image.

setZoom

Type

(
  zoom: number,
) => void

Description

Function to set the zoom level of the image.

translations

Type

{
  listLabel?: string
}

Description

Localized labels for the popup controls.

viewportRect

Type

{
  bottom: number
  height: number
  left: number
  right: number
  top: number
  width: number
}

Description

The viewport rectangle dimensions and position.

zoom

Type

number

Description

The current zoom level of the image.

zoomBy

Type

(
  delta: number,
) => void

Description

Function to zoom the image by a relative amount.

Composite API

<ImageViewer.Root>

src and alt are defaults that either image can override.

Groups the image viewer parts and manages their state.

Prop	Type	Default
alt Default alternative text for StaticImage and ViewportImage.	string
defaultFlip The initial flip state to apply to the image.	{ horizontal: boolean vertical: boolean }	{ horizontal: false, vertical: false }
defaultOpen Whether the popup is initially open.	boolean	false
defaultRotation The initial rotation to apply to the image in degrees.	number	0
defaultZoom The initial zoom factor to apply to the image.	number	1
dir The document's text/writing direction.	'ltr' \| 'rtl'	'ltr'
flip The controlled flip state of the image.	{ horizontal: boolean vertical: boolean }
getRootNode A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.	() => \| Node \| ShadowRoot \| Document
ids The ids of the image viewer elements	Partial<{ root: string viewport: string viewportImage: string }>
maxZoom The maximum zoom factor allowed.	number	5
minZoom The minimum zoom factor allowed.	number	1
nudgeStep The base nudge step for keyboard arrow keys (in pixels).	number	1
nudgeStepCtrl The nudge step when Ctrl/Cmd key is held (in pixels).	number	50
nudgeStepShift The nudge step when Shift key is held (in pixels).	number	10
onFlipChange Callback fired when the flip state changes.	(details: { flip: { horizontal: boolean vertical: boolean } }) => void
onOpenChange Called when the popup requests an open state change.	( open: boolean, ) => void
onRotationChange Callback fired when the rotation changes.	(details: { rotation: number }) => void
onZoomChange Callback fired when the zoom level changes.	(details: { zoom: number }) => void
open The controlled popup open state.	boolean
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
rotation The controlled rotation of the image in degrees (0 - 360).	number
src Default image source for StaticImage and ViewportImage.	string
translations Specifies the localized strings that identify accessibility elements and their states.	{ listLabel?: string }
zoom The controlled zoom level of the image.	number
zoomSensitivity Controls how responsive pinch-to-zoom is.	number	2
zoomStep The amount of zoom applied per wheel step.	number	0.1

alt

Type

string

Description

Default alternative text for StaticImage and ViewportImage.

defaultFlip

Type

{
  horizontal: boolean
  vertical: boolean
}

Description

The initial flip state to apply to the image.

defaultOpen

Type

boolean

Description

Whether the popup is initially open.

defaultRotation

Type

number

Description

The initial rotation to apply to the image in degrees.

defaultZoom

Type

number

Description

The initial zoom factor to apply to the image.

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

flip

Type

{
  horizontal: boolean
  vertical: boolean
}

Description

The controlled flip state of the image.

getRootNode

Type

() =>
| Node
| ShadowRoot
| Document

Description

A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.

ids

Type

Partial<{
  root: string
  viewport: string
  viewportImage: string
}>

Description

The ids of the image viewer elements

maxZoom

Type

number

Description

The maximum zoom factor allowed.

minZoom

Type

number

Description

The minimum zoom factor allowed.

nudgeStep

Type

number

Description

The base nudge step for keyboard arrow keys (in pixels).

nudgeStepCtrl

Type

number

Description

The nudge step when Ctrl/Cmd key is held (in pixels).

nudgeStepShift

Type

number

Description

The nudge step when Shift key is held (in pixels).

onFlipChange

Type

(details: {
  flip: {
    horizontal: boolean
    vertical: boolean
  }
}) => void

Description

Callback fired when the flip state changes.

onOpenChange

Type

(
  open: boolean,
) => void

Description

Called when the popup requests an open state change.

onRotationChange

Type

(details: {
  rotation: number
}) => void

Description

Callback fired when the rotation changes.

onZoomChange

Type

(details: {
  zoom: number
}) => void

Description

Callback fired when the zoom level changes.

open

Type

boolean

Description

The controlled popup open state.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

rotation

Type

number

Description

The controlled rotation of the image in degrees (0 - 360).

src

Type

string

Description

Default image source for StaticImage and ViewportImage.

translations

Type

{
  listLabel?: string
}

Description

Specifies the localized strings that identify accessibility elements and their states.

zoom

Type

number

Description

The controlled zoom level of the image.

zoomSensitivity

Type

number

Description

Controls how responsive pinch-to-zoom is.

zoomStep

Type

number

Description

The amount of zoom applied per wheel step.

Attribute / Property	Value
`className`	'qui-image-viewer__root'
`data-image-viewer-part`	'root'
`data-panning`
`data-pinch`
`style`	CSSProperties

className

Value

'qui-image-viewer__root'

data-image-viewer-part

Value

'root'

data-panning

Value

data-pinch

Value

style

Value

CSSProperties

<ImageViewer.Trigger>

A static preview button that opens the image popup.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-image-viewer__trigger'
`data-dialog-part`	'trigger'
`data-state`	\| 'open' \| 'closed'

className

Value

'qui-image-viewer__trigger'

data-dialog-part

Value

'trigger'

data-state

Value

| 'open'
| 'closed'

<ImageViewer.RootProvider>

Groups image viewer parts using an externally created API.

Prop	Type
value ^* An image viewer API created with useImageViewer.	ImageViewerApi
alt Default alternative text for StaticImage and ViewportImage.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
src Default image source for StaticImage and ViewportImage.	string

value

Type

ImageViewerApi

Description

An image viewer API created with useImageViewer.

alt

Type

string

Description

Default alternative text for StaticImage and ViewportImage.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

src

Type

string

Description

Default image source for StaticImage and ViewportImage.

Shortcuts

<ImageViewer.FloatingPortal>

ImageViewer.FloatingPortal combines the portal, backdrop, positioner, and content elements.

import {Portal} from "@qualcomm-ui/react-core/portal"

;<Portal {...props}>
  <ImageViewer.Backdrop {...backdropProps} />
  <ImageViewer.Positioner {...positionerProps}>
    <ImageViewer.Content {...contentProps}>{children}</ImageViewer.Content>
  </ImageViewer.Positioner>
</Portal>

Combines a portal, backdrop, positioner, and content for the image popup.

Prop	Type
backdropProps Props applied to the backdrop.	ImageViewerBackdropProps
children Popup contents, including the viewport and controls.	ReactNode
container Specify to override the container element.	\| HTMLElement \| ShadowRoot \| RefObject< HTMLElement \| ShadowRoot >
contentProps Props applied to the content.	ImageViewerContentProps
disabled Disable the portal conditionally. This causes the children to be rendered as-is.	boolean
positionerProps Props applied to the positioner.	ImageViewerPositionerProps

backdropProps

Type

ImageViewerBackdropProps

Description

Props applied to the backdrop.

children

Type

ReactNode

Description

Popup contents, including the viewport and controls.

container

Type

| HTMLElement
| ShadowRoot
| RefObject<
    HTMLElement | ShadowRoot
  >

Description

Specify to override the container element.

contentProps

Type

ImageViewerContentProps

Description

Props applied to the content.

disabled

Type

boolean

Description

Disable the portal conditionally. This causes the children to be rendered as-is.

positionerProps

Type

ImageViewerPositionerProps

Description

Props applied to the positioner.

<ImageViewer.Backdrop>

Dims the page behind the expanded image.

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-image-viewer__backdrop'
`data-dialog-part`	'backdrop'
`data-state`	\| 'open' \| 'closed'
`hidden`	boolean

className

Value

'qui-image-viewer__backdrop'

data-dialog-part

Value

'backdrop'

data-state

Value

| 'open'
| 'closed'

hidden

Value

boolean

<ImageViewer.Positioner>

Positions the popup inside the padded browser viewport.

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-image-viewer__positioner'
`data-dialog-part`	'positioner'
`style`	CSSProperties

className

Value

'qui-image-viewer__positioner'

data-dialog-part

Value

'positioner'

style

Value

CSSProperties

<ImageViewer.Content>

Contains the image viewport and an optional row of controls.

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-image-viewer__content'
`data-dialog-part`	'content'
`data-state`	\| 'open' \| 'closed'
`hidden`	boolean
`tabIndex`	-1

className

Value

'qui-image-viewer__content'

data-dialog-part

Value

'content'

data-state

Value

| 'open'
| 'closed'

hidden

Value

boolean

tabIndex

Value

-1

<ImageViewer.CloseButton>

Closes the popup and restores the initial transform.

Prop	Type	Default
density The density of the button. Governs padding and height.	\| 'default' \| 'compact'	'default'
disabled Controls whether the component is interactive. When `true`, pointer/focus events are blocked, and the component is visually dimmed.	boolean	false
emphasis The style variant of the button. Governs colors.	\| 'neutral' \| 'primary' \| 'danger' \| 'persistent-white' \| 'persistent-black' \| 'inverse' \| 'white-persistent' \| 'black-persistent'	'neutral'
icon Icon displayed in the close button.	\| LucideIcon \| ReactNode	Minimize2
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
shape Governs the shape of the icon button.	\| 'square' \| 'rounded'	'square'
size The size of the component and its icons.	\| 'sm' \| 'md' \| 'lg'	'md'
variant The style variant of the button. Governs colors.	\| 'fill' \| 'ghost' \| 'outline'	'fill'

density

Type

| 'default'
| 'compact'

Description

The density of the button. Governs padding and height.

disabled

Type

boolean

Description

Controls whether the component is interactive. When true, pointer/focus events are blocked, and the component is visually dimmed.

emphasis

Type

| 'neutral'
| 'primary'
| 'danger'
| 'persistent-white'
| 'persistent-black'
| 'inverse'
| 'white-persistent'
| 'black-persistent'

Description

The style variant of the button. Governs colors.

icon

Type

| LucideIcon
| ReactNode

Description

Icon displayed in the close button.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

shape

Type

| 'square'
| 'rounded'

Description

Governs the shape of the icon button.

size

Type

| 'sm'
| 'md'
| 'lg'

Description

The size of the component and its icons.

variant

Type

| 'fill'
| 'ghost'
| 'outline'

Description

The style variant of the button. Governs colors.

Attribute / Property	Value
`className`	'qui-image-viewer__close-trigger'
`data-dialog-part`	'close-trigger'

Viewer API

<ImageViewer.Viewport>

The focusable viewport containing ViewportImage and handling pan and zoom.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-image-viewer__viewport'
`data-image-viewer-part`	'viewport'
`data-ownedby`	string
`data-panning`
`data-ready`
`style`	CSSProperties
`tabIndex`	0

className

Value

'qui-image-viewer__viewport'

data-image-viewer-part

Value

'viewport'

data-ownedby

Value

string

data-panning

Value

data-ready

Value

style

Value

CSSProperties

tabIndex

Value

<ImageViewer.StaticImage>

The inline image. Its src and alt default to the root values.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-image-viewer__static-image'

<ImageViewer.ViewportImage>

The expanded image inside Viewport. Its src and alt default to the root values.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-image-viewer__viewport-image'
`data-flip-horizontal`
`data-flip-vertical`
`data-image-viewer-part`	'viewport-image'
`data-ownedby`	string
`data-ready`
`style`	CSSProperties

className

Value

'qui-image-viewer__viewport-image'

data-flip-horizontal

Value

data-flip-vertical

Value

data-image-viewer-part

Value

'viewport-image'

data-ownedby

Value

string

data-ready

Value

style

Value

CSSProperties

<ImageViewer.Context>

Prop	Type
children ^* Renders content using the current image viewer API.	RenderProp<ImageViewerApi>

children

Type

RenderProp<ImageViewerApi>

Description

Renders content using the current image viewer API.

<ImageViewer.ZoomInButton>

Increases the image zoom level.

Prop	Type	Default
density The density of the button. Governs padding and height.	\| 'default' \| 'compact'	'default'
disabled Controls whether the component is interactive. When `true`, pointer/focus events are blocked, and the component is visually dimmed.	boolean	false
emphasis The style variant of the button. Governs colors.	\| 'neutral' \| 'primary' \| 'danger' \| 'persistent-white' \| 'persistent-black' \| 'inverse' \| 'white-persistent' \| 'black-persistent'	'neutral'
icon Icon displayed in the button.	\| LucideIcon \| ReactNode	ZoomIn
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
shape Governs the shape of the icon button.	\| 'square' \| 'rounded'	'square'
size The size of the component and its icons.	\| 'sm' \| 'md' \| 'lg'	'md'
variant The style variant of the button. Governs colors.	\| 'fill' \| 'ghost' \| 'outline'	'fill'

density

Type

| 'default'
| 'compact'

Description

The density of the button. Governs padding and height.

disabled

Type

boolean

Description

Controls whether the component is interactive. When true, pointer/focus events are blocked, and the component is visually dimmed.

emphasis

Type

| 'neutral'
| 'primary'
| 'danger'
| 'persistent-white'
| 'persistent-black'
| 'inverse'
| 'white-persistent'
| 'black-persistent'

Description

The style variant of the button. Governs colors.

icon

Type

| LucideIcon
| ReactNode

Description

Icon displayed in the button.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

shape

Type

| 'square'
| 'rounded'

Description

Governs the shape of the icon button.

size

Type

| 'sm'
| 'md'
| 'lg'

Description

The size of the component and its icons.

variant

Type

| 'fill'
| 'ghost'
| 'outline'

Description

The style variant of the button. Governs colors.

Attribute / Property	Value
`className`	'qui-image-viewer__zoom-in-trigger'
`data-image-viewer-part`	'zoom-in-trigger'

className

Value

'qui-image-viewer__zoom-in-trigger'

data-image-viewer-part

Value

'zoom-in-trigger'

<ImageViewer.ZoomOutButton>

Decreases the image zoom level.

Prop	Type	Default
density The density of the button. Governs padding and height.	\| 'default' \| 'compact'	'default'
disabled Controls whether the component is interactive. When `true`, pointer/focus events are blocked, and the component is visually dimmed.	boolean	false
emphasis The style variant of the button. Governs colors.	\| 'neutral' \| 'primary' \| 'danger' \| 'persistent-white' \| 'persistent-black' \| 'inverse' \| 'white-persistent' \| 'black-persistent'	'neutral'
icon Icon displayed in the button.	\| LucideIcon \| ReactNode	ZoomOut
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
shape Governs the shape of the icon button.	\| 'square' \| 'rounded'	'square'
size The size of the component and its icons.	\| 'sm' \| 'md' \| 'lg'	'md'
variant The style variant of the button. Governs colors.	\| 'fill' \| 'ghost' \| 'outline'	'fill'

density

Type

| 'default'
| 'compact'

Description

The density of the button. Governs padding and height.

disabled

Type

boolean

Description

Controls whether the component is interactive. When true, pointer/focus events are blocked, and the component is visually dimmed.

emphasis

Type

| 'neutral'
| 'primary'
| 'danger'
| 'persistent-white'
| 'persistent-black'
| 'inverse'
| 'white-persistent'
| 'black-persistent'

Description

The style variant of the button. Governs colors.

icon

Type

| LucideIcon
| ReactNode

Description

Icon displayed in the button.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

shape

Type

| 'square'
| 'rounded'

Description

Governs the shape of the icon button.

size

Type

| 'sm'
| 'md'
| 'lg'

Description

The size of the component and its icons.

variant

Type

| 'fill'
| 'ghost'
| 'outline'

Description

The style variant of the button. Governs colors.

Attribute / Property	Value
`className`	'qui-image-viewer__zoom-out-trigger'
`data-image-viewer-part`	'zoom-out-trigger'

className

Value

'qui-image-viewer__zoom-out-trigger'

data-image-viewer-part

Value

'zoom-out-trigger'

<ImageViewer.ResetButton>

Restores the initial image transforms.

Prop	Type	Default
density The density of the button. Governs padding and height.	\| 'default' \| 'compact'	'default'
disabled Controls whether the component is interactive. When `true`, pointer/focus events are blocked, and the component is visually dimmed.	boolean	false
emphasis The style variant of the button. Governs colors.	\| 'neutral' \| 'primary' \| 'danger' \| 'persistent-white' \| 'persistent-black' \| 'inverse' \| 'white-persistent' \| 'black-persistent'	'neutral'
icon Icon displayed in the button.	\| LucideIcon \| ReactNode	RefreshCw
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
shape Governs the shape of the icon button.	\| 'square' \| 'rounded'	'square'
size The size of the component and its icons.	\| 'sm' \| 'md' \| 'lg'	'md'
variant The style variant of the button. Governs colors.	\| 'fill' \| 'ghost' \| 'outline'	'fill'

density

Type

| 'default'
| 'compact'

Description

The density of the button. Governs padding and height.

disabled

Type

boolean

Description

Controls whether the component is interactive. When true, pointer/focus events are blocked, and the component is visually dimmed.

emphasis

Type

| 'neutral'
| 'primary'
| 'danger'
| 'persistent-white'
| 'persistent-black'
| 'inverse'
| 'white-persistent'
| 'black-persistent'

Description

The style variant of the button. Governs colors.

icon

Type

| LucideIcon
| ReactNode

Description

Icon displayed in the button.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

shape

Type

| 'square'
| 'rounded'

Description

Governs the shape of the icon button.

size

Type

| 'sm'
| 'md'
| 'lg'

Description

The size of the component and its icons.

variant

Type

| 'fill'
| 'ghost'
| 'outline'

Description

The style variant of the button. Governs colors.

Attribute / Property	Value
`className`	'qui-image-viewer__reset-trigger'
`data-image-viewer-part`	'reset-trigger'

Last updated on Oct 21, 2026 by Ryan Bower

Icon Button

Inline Icon Button