Image

View Code

Installation

The component is exported from @by/experience-system. Add the package with your package manager:

pnpm add @by/experience-system

In this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.

Composition

Image is a single self-contained component—no sub-parts are exported. The internal structure differs by mode:

Image (mode="overlay")
└── Popover (thumbnail anchor → full-size popover on hover/focus)

Image (mode="full-screen")
└── trigger div (thumbnail + hover overlay icon)
└── Dialog (full-size image in modal on click)

Image uses Radix Popover in overlay mode and Radix Dialog in full-screen mode. A Skeleton is rendered in place of both images when loading={true}.

Usage

import { Image } from '@by/experience-system';

Image is a client component ('use client'). Use it inside a Client Component or a dynamic import when using the Next.js App Router.

Overlay mode

Hovering (or focusing) the thumbnail shows the full image in a popover:

<Image
  mode="overlay"
  chipImage="/path/to/thumb.jpg"
  fullImage="/path/to/large.jpg"
  chipAlt="Product thumbnail"
  chipWidth={60}
  chipHeight={60}
  fullWidth={400}
  fullHeight={300}
/>

Full-screen mode

Clicking the thumbnail opens the full image in a modal dialog. An aria-label is required to name the interactive trigger:

<Image
  mode="full-screen"
  chipImage="/path/to/thumb.jpg"
  fullImage="/path/to/large.jpg"
  chipAlt="Product image"
  aria-label="Open full-size product image"
  chipWidth={60}
  chipHeight={60}
  fullWidth={800}
  fullHeight={600}
/>

Examples

Overlay

Hover over a thumbnail to reveal the full image in a popover. This mode is suited for data tables and grids where the user scans many rows.

View Code

Full-screen

Click the thumbnail to open the full image in a modal dialog. A maximize icon appears on hover. Use this mode when the user needs to inspect fine detail.

View Code

Loading skeleton

Pass loading={true} while the image URL is being fetched. The skeleton inherits the chipWidth and chipHeight dimensions.

API Reference

Image is a Experience System-authored component. There is no upstream Radix primitive page for the combined API; behavior of the internal Popover and Dialog follows Radix Popover and Radix Dialog respectively.

Image

The single exported component. The accepted props depend on the mode discriminant.

Common props (both modes):

mode="full-screen" additional prop:

Accessibility

Image handles accessibility at two levels depending on mode:

• Overlay — The thumbnail is a plain <img> (with alt from chipAlt). The popover is opened on mouseenter / focus and is aria-hidden from keyboard navigation (onOpenAutoFocus is suppressed). Provide a meaningful chipAlt for screen readers.
• Full-screen — The thumbnail wrapper has role="button", tabIndex={0}, and an aria-label (required prop). The dialog includes a visually-hidden <DialogTitle> ("Full-size image") and <DialogDescription> (falls back to chipAlt). The close button has aria-label="Close". Keyboard: Enter or Space opens the dialog; Esc closes it (handled by Radix Dialog).

Underlying Radix behavior: Radix Popover accessibility and Radix Dialog accessibility.

Keyboard interactions

Source in the repo: packages/experience-system/src/components/Image/Image.tsx. Agent-oriented contracts: packages/experience-system/src/components/Image/Image.instructions.md.