@fluixi-ui/image

An image with loading and error states for Fluixi UI.

Layers the <img>, an optional placeholder (while loading), and a fallback (on error) inside a sized box; give it a width/height or aspect ratio and it fades the image in on load, swapping to the fallback if the source fails.

import { Image } from '@fluixi-ui/image';
import { Skeleton } from '@fluixi-ui/skeleton';

<Image
  src={product.thumbnail}
  alt={product.title}
  style="width:64px;height:64px;border-radius:8px"
  placeholder={<Skeleton style="width:100%;height:100%" />}
  fallback={<span>📷</span>}
/>

Optimization & lazy loading

The component never optimizes the bytes itself — it stays framework-agnostic and asks a pluggable loader for the right URLs, then leans on native browser features. (A built-in optimization endpoint, if you want one, belongs in the framework/meta-framework and would just be plugged in via loader.)

<Image
  src="/products/mug.jpg"
  alt="Mug"
  aspectRatio={1}
  sizes="(max-width: 600px) 100vw, 240px"
  widths={[120, 240, 480]}
  loader={({ src, width, quality }) => `https://cdn.example.com${src}?w=${width}&q=${quality ?? 75}`}
  blurDataURL={mug.lqip}
/>

// Above-the-fold hero: eager + high fetch priority
<Image src={hero} alt="" priority style="width:100%" />

Props

Extends the native <img> attributes, plus:

| Prop | Type | Description | | --- | --- | --- | | lazy | boolean | loading="lazy" + decoding="async" (default true). | | priority | boolean | Load eagerly with fetchpriority="high". | | loader | (args: { src; width; quality? }) => string | Map to an optimized URL; with widths, builds a srcset. | | widths | number[] | Candidate widths for the generated srcset. | | sizes | string | Responsive sizes attribute. | | srcset | string | Explicit srcset when not using a loader. | | quality | number | Forwarded to the loader. | | aspectRatio | number \| string | Reserve space to avoid layout shift. | | blurDataURL | string | Tiny blurred data URL shown until load (LQIP). | | placeholder | JSX.Element | Shown while loading (ignored if blurDataURL set). | | fallback | JSX.Element | Shown instead of the image on error. | | onStatusChange | (status) => void | Load lifecycle. |

Reflects data-status on [data-image]. Styled by @fluixi-ui/tokens ([data-image], [data-image-img], [data-image-blur]).