Data display

Image

Styles accessible images while preserving Astro, Next.js, and browser-native optimization.

View preview API reference View in Figma

FrameworksAstro · React · Elements

Registry commandlumen add Image

InteractionNative markup

Design sourceLinked component node

See it and copy it

Framework example

Choose Astro, React, or Elements to compare native usage against the shared visual output. Each example assumes the framework-level setup is already complete.

Framework usage

Switch targets to compare the adapter code. The preview stays visually stable because all three packages share the same tokens and ui-* class contract.

---
import { Image } from '@santi020k/lumen-astro'
---

<Image
  alt="Lumen UI logo"
  height="80"
  layout="fixed"
  src="/logo.svg"
  width="310"
/>

import NextImage from 'next/image'
import { Image as LumenImage } from '@santi020k/lumen-react'

export const Example = () => (
  <LumenImage
    alt="Lumen UI logo"
    as={NextImage}
    height={80}
    src="/logo.svg"
    width={310}
  />
)

<img
  alt="Lumen UI logo"
  class="ui-image"
  decoding="async"
  height="80"
  loading="lazy"
  src="/logo.svg"
  width="310"
/>

Edit Image in browser

Keep the host framework in control

Astro and Next.js optimization

Lumen owns the final image styling, including ui-image and optional dark-mode inversion. It does not run a second image pipeline. The Astro adapter delegates toastro:assets; the React adapter renders the optimizer supplied throughas and forwards its props.

Astro: import local assets

A static import supplies intrinsic dimensions and enables build-time processing. Choose layout="full-width" for viewport-width media,"constrained" for fluid media with a maximum width, or"fixed" for a fixed-size asset. Astro generates the responsivesrcset, sizes, and layout styles.

---
import { Image } from '@santi020k/lumen-astro'
import hero from '../assets/hero.jpg'
---

<Image
  alt="Mountain valley at sunrise"
  layout="full-width"
  priority
  quality={80}
  src={hero}
/>

---
import { Image } from '@santi020k/lumen-astro'
import hero from '../assets/hero.jpg'
---

<Image
  alt="Mountain valley at sunrise"
  layout="full-width"
  priority
  quality={80}
  src={hero}
/>

Use priority only for the likely LCP image. Astro applies eager loading, high fetch priority, and synchronous decoding.
Public-directory and remote string sources need known dimensions. UseinferSize for an authorized remote source when its dimensions are not available, and configure remote image domains in the Astro app.
Override widths, sizes, quality, orformat only when the layout or delivery target calls for it.

Astro Image reference

Next.js: pass next/image through as

Passing NextImage keeps Next.js in charge of resizing, format negotiation, caching, placeholders, and preloading. With an optimizer supplied, Lumen does not inject its native loading="lazy" default.

import NextImage from 'next/image'
import { Image as LumenImage } from '@santi020k/lumen-react'
import hero from './hero.jpg'

export function HeroImage() {
  return (
    <LumenImage
      alt="Mountain valley at sunrise"
      as={NextImage}
      placeholder="blur"
      preload
      sizes="(max-width: 768px) 100vw, 50vw"
      src={hero}
      style={{ height: 'auto', width: '100%' }}
    />
  )
}

import NextImage from 'next/image'
import { Image as LumenImage } from '@santi020k/lumen-react'
import hero from './hero.jpg'

export function HeroImage() {
  return (
    <LumenImage
      alt="Mountain valley at sunrise"
      as={NextImage}
      placeholder="blur"
      preload
      sizes="(max-width: 768px) 100vw, 50vw"
      src={hero}
      style={{ height: 'auto', width: '100%' }}
    />
  )
}

Static imports provide dimensions and can provide blur data automatically. String or remote sources need width and height, unlessfill is used.
Add an accurate sizes value for responsive or fillimages; without it the browser can select an unnecessarily large candidate.
In Next.js 16+, use preload for the one clear LCP image; do not combine it with loading or fetchPriority. Leave below-the-fold images on Next.js defaults.
Allow remote sources with narrow images.remotePatterns entries innext.config. For fill, give the parent a positioned box and a real size.

Next.js Image reference

For both frameworks: write useful alt text (oralt="" for decoration), preserve intrinsic aspect ratio, keepsizes aligned with the rendered layout, and reserve eager or priority loading for the page’s likely LCP image. Use invertOnDark only for monochrome artwork, not photographs.

Choose your target

Add this component

Choose the package for your runtime. All adapters share the Lumen stylesheet. Use the matching registry command when you want a local wrapper for that framework.

pnpm add @santi020k/lumen-astro

pnpm add @santi020k/lumen-astro

lumen add Image

lumen add Image

pnpm add @santi020k/lumen-react

pnpm add @santi020k/lumen-react

lumen add Image --target react

lumen add Image --target react

pnpm add @santi020k/lumen-elements

pnpm add @santi020k/lumen-elements

lumen add Image --target elements

lumen add Image --target elements

API reference

Lumen-specific props and runtime attributes for the Astro primitive. React props follow the same names; Elements use equivalent kebab-case attributes where custom elements expose them.

Attribute	Values	Default	Description
src	ImageMetadata \| string	required	Uses astro:assets in Astro; React passes the source to the native img or the optimizer supplied through as.
alt	string	required	Provides an accessible description; use an empty string for decorative images.
loading	"lazy" \| "eager"	Astro/native img: "lazy"	Defers off-screen loading. When as is set in React, Lumen leaves the optimizer default untouched unless this prop is explicit.
layout	"fixed" \| "constrained" \| "full-width" \| "none"	-	Astro only: generates responsive dimensions, srcset, sizes, and layout styles through astro:assets.
width, height	number \| string	source metadata or required	Set intrinsic dimensions for public and remote sources. Astro and Next.js can derive them from supported static imports.
widths, sizes	number[]; string	layout-dependent	Astro responsive controls. Next.js also uses sizes to generate and select an efficient width-based srcset.
quality, format	framework-supported values	framework default	Passes image encoding choices to astro:assets or to the React optimizer supplied through as.
priority	boolean	false	Astro only: marks the likely LCP image for immediate loading, synchronous decoding, and high fetch priority.
preload, fill, placeholder	NextImage props	Next.js defaults	Next.js only through as={NextImage}: keeps preloading, fill layout, and placeholder generation under next/image control.
invertOnDark	boolean	false	Inverts monochrome artwork in dark themes while preserving colorful images by default.
as	React ElementType	"img"	React only: renders a compatible optimizer such as next/image while retaining Lumen classes and forwarding optimizer props.
class, className	string	""	Merges custom classes with the generated ui-* root classes.
...native attributes	HTML attributes	-	Forwards standard attributes to the root element unless the component consumes them.