API and Development
@prepared911/ui/image is the design-system Image. Pass src for a URL or raster image, or svg for a trusted inline SVG component (ComponentType<SVGProps<SVGSVGElement>>). Those two sources are mutually exclusive. An inline SVG takes size={{ block, inline }} from the space scale (--space-*) and paints with currentColor. A meaningful alt is role="img" plus aria-label. decorative or alt="" sets aria-hidden="true" and focusable="false". Image does not add title or desc.
The ui-core Image documented below still has four modes: pass src for URL/raster images (native <img>), svg for trusted inline SVG components from a local ?react import, or lightSrc/darkSrc / lightSvg/darkSvg for theme-aware variants. Shared layout props (fill, width, height, objectFit, objectPosition) apply in all modes. URL mode additionally supports lazy loading, priority preloading, blur placeholders, load/error callbacks, responsive srcSet/sizes, and alternate-format sources (rendered as a native <picture>).
Themed modes render both sources and toggle visibility with CSS keyed on ancestor .light / .light-theme / .radix-themes.light or .dark / .dark-theme / .radix-themes.dark classes. In themed modes, id is applied to a display: contents themed root, and onLoad / onError are forwarded to both URL variants.
Modeled on the Next.js Image layout/perf API. Server-only optimization props (loader, quality, unoptimized) are not supported in ui-core.
Pass exactly one of alt (accessible description) or decorative (skips the image for screen readers) — passing both, or neither, is a type error.
| Name | Type | Default | Description |
|---|---|---|---|
alt | LocalizedMessage | — | Accessible name; rendered as the alt attribute.
Accessible name. Rendered as aria-label with role="img". An empty string is decorative. |
allowRemoteSource | boolean | — | When true, development src checks allow remote http(s): URLs. Avatar sets this so API photo
URLs match ui-core; other call sites stay on same-origin static assets by default.
Remote URL checks apply to src, not an inline SVG. |
aria-description | LocalizedMessage | — | Extended description for assistive tech. |
aria-label | LocalizedMessage | — | Accessible name when the visible label is insufficient. |
aria-placeholder | LocalizedMessage | — | Hint for an empty control. |
aspectRatio | ImageAspectRatio | — | Intrinsic aspect ratio for width-driven layout; height comes from the ratio when the parent block size is auto.
CSS aspect-ratio when one size axis should drive the other. |
decorative | boolean | — | When omitted or false, the image is meaningful and must supply alt.
Marks the image as decorative; no accessible name is allowed.
When omitted or false, the graphic is meaningful and must supply alt.
Marks the graphic as decorative. Renders aria-hidden="true" and focusable="false". |
loading | ImageLoading | — | Native lazy-loading hint. Defaults to {@link ImageLoading.Eager}.
Native loading applies to img, not an inline SVG. |
objectFit | ImageObjectFit | — | How the bitmap fits its layout box. Defaults to {@link ImageObjectFit.Fill}.
Object fit applies to img, not an inline SVG. |
objectPosition | ImageObjectPosition | — | Focal point when objectFit crops. Omitted uses the browser default (center).
Object position applies to img, not an inline SVG. |
ref | ((instance: HTMLImageElement | null) => void | (() => VoidOrUndefinedOnly)) | RefObject<HTMLImageElement | null> | ((instance: SVGSVGElement | null) => void | (() => VoidOrUndefinedOnly)) | RefObject<...> | null | — | Ref to the primary img (the light-theme source when two sources render).
Ref to the rendered svg. |
size | ImageSvgSize | — | Space-scale size. Mutually exclusive with src; URL images are sized by Box or Grid.
Block and inline size from the space scale. URL images have no size prop (IMG-4); an inline
SVG has no parent box of its own, and aspectRatio presets do not match wordmark ratios. |
src | string | — | Trusted image URL (relative path or same-origin static asset).
URL source. Mutually exclusive with svg. |
srcDark | string | — | Optional dark-theme source; when it differs from src, a second img swaps in under data-theme="dark".
Dark URL source. Mutually exclusive with svg. |
svg | ComponentType<SVGProps<SVGSVGElement>> | — | Inline SVG source. Mutually exclusive with src.
Trusted inline SVG component, for example an SVGR ?react import.
Image sets accessibility and size on this component; it does not add title or desc. |
title | LocalizedMessage | — | Native tooltip; accessibility hint, not visible UI title text. |
src fallback. The browser takes the first type it can decode. List newest-first (AVIF → WebP).