Image

Usage

Prefer <Image> over the plain markdown ![alt](src) syntax when you need any of:

• A caption below the image

• A dark-mode alternative source

• Click-to-zoom lightbox behavior

• Explicit width / height for layout stability

<Image
  src="/screenshots/dashboard.png"
  alt="CodivDocs dashboard showing the project list"
/>

With caption

<Image
  src="/screenshots/architecture.png"
  alt="Multi-tenant request flow"
  caption="Every request is routed by subdomain before hitting the tenant's page"
/>

Dark mode variant

Pass a darkSrc for a second image that renders when the reader has dark theme active. Useful for diagrams with light backgrounds that become unreadable on dark:

<Image
  src="/diagrams/api-flow-light.svg"
  darkSrc="/diagrams/api-flow-dark.svg"
  alt="API request flow diagram"
  caption="Authentication and request routing"
/>

The swap is handled via CSS — the light and dark variants are both in the DOM but one is hidden based on the current data-docs-theme attribute.

Lightbox

Set lightbox to true to let readers click the image and expand it to full screen:

<Image
  src="/screenshots/dashboard-full.png"
  alt="Full CodivDocs dashboard with sidebar and content panel"
  lightbox
/>

The click opens a dimmed overlay with the image centered and a close button in the corner. Esc or clicking the backdrop also closes.

Fixed dimensions

For layout stability (no cumulative layout shift), specify explicit width and height in pixels:

<Image
  src="/logos/partner.png"
  alt="Partner logo"
  width={200}
  height={80}
/>

Aspect ratio

When the source size is unknown (external URL, user upload), fix the aspect ratio to prevent layout jumps:

<Image
  src="https://cdn.example.com/hero.jpg"
  alt="Hero image"
  aspectRatio="16/9"
/>

Accessibility

Props