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="https://placehold.co/800x400/1e293b/white?text=Dashboard+Screenshot"
  alt="NookDocs dashboard showing the project list"
/>

With caption

<Image
  src="https://placehold.co/800x300/0f172a/94a3b8?text=Architecture+Diagram"
  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="https://placehold.co/600x300/f8fafc/334155?text=Light+Mode+Diagram"
  darkSrc="https://placehold.co/600x300/0f1117/c8cad3?text=Dark+Mode+Diagram"
  alt="API request flow diagram"
  caption="This image swaps based on your theme"
/>

Lightbox

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

<Image
  src="https://placehold.co/800x500/1e293b/white?text=Click+to+Zoom"
  alt="Full dashboard screenshot"
  lightbox
  caption="Click the image to enlarge"
/>

Fixed dimensions

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

<Image
  src="https://placehold.co/200x80/16a34a/white?text=Logo"
  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://placehold.co/1600x900/0f172a/f0f0f3?text=16:9+Aspect+Ratio"
  alt="Hero image"
  aspectRatio="16/9"
/>

Local paths and external URLs

src takes either, and they behave differently.

A path like /images/settings.png resolves to a file in your repo's public/ folder, and the image goes through the optimizer: readers get a resized AVIF or WebP matched to their screen, so the file you commit is not the file they download.

An https:// URL is served exactly as uploaded — the optimizer only handles images NookDocs hosts. Nothing enters your repo, which is what makes it the right choice for video and for anything large, but the size you upload is the size every reader pays on every device.

<Image src="/images/settings.png" alt="The project settings screen" />

<Image src="https://cdn.example.com/docs/settings.png" alt="The project settings screen" />

Accessibility

Props