RasterImage

A React component for rendering raster images (JPG/PNG/WebP/AVIF, etc.) with optional responsive sources and graceful fallback when no image is available. SVG sources are detected automatically and rendered as-is. The component integrates with the UXF image resizer utilities to generate optimized images for different breakpoints.

Installation / CSS dependency

Add the package stylesheet to your global CSS if you haven't already:

@import url("@uxf/ui/raster-image/raster-image.css");

When to use

• You need a drop-in <img/>-like component that works with UXF's resizer service.
• You want responsive images via <picture/> + <source/> with different widths/heights per breakpoint.
• You want consistent empty-state rendering when the image is missing.

Basic usage

import { RasterImage } from "@uxf/ui/raster-image";

export function CardThumb() {
  return (
    <RasterImage
      alt="A beautiful landscape"
      src="images/landscape.jpg"
      width={400}
      height={300}
      loading="lazy"
    />
  );
}

• Provide at least one of width or height. If you provide both, the exact dimensions will be requested from the resizer.
• If the provided source is an SVG, the component will render a simple <img/> with the SVG URL (no resizer involved).

Modes (object-fit helpers)

Use the mode prop to control fit behavior via CSS classes:

• mode="contain" → adds classes to make the image fit entirely inside the box without cropping.
• mode="cover" → adds classes to cover the box, possibly cropping.
• mode="responsive" → reserved for responsive layouts; adds a class you can target. Actual responsiveness is configured via widths/heights props below.

Example:

<RasterImage alt="Product" src="p/1.jpg" width={320} height={320} mode="cover" />

Responsive images (sizes/srcset)

To provide multiple sources for different viewports, pass widths and/or heights arrays and optionally breakpoints. (Default breakpoints are passed from UiContext.) The component will render a <picture/> with <source/> tags via ResponsiveImgSources.

import { em } from "./em";

<RasterImage
    alt="Hero"
    src="images/hero.jpg"
    // Desired element box in CSS might be responsive; request multiple candidate widths
    widths={[360, 640, 960, 1280]}
    // Optional heights if you need height-based variants
    // heights={[180, 320, 480, 640]}
    // Optional map of named breakpoints to CSS media queries (passed through to `<source media="..."/>`)
    breakpoints={{
        sm: em(576),
        md: em(768),
        lg: em(1024)
    }}
    // You can still provide width/height to define the fallback `<img/>` dimensions
    width={960}
    height={540}
/>

Notes:

• If a resizer URL can be constructed for the provided src, the component renders a <picture/> with responsive sources plus a fallback <img/>.
• If resizer cannot be used for the src, or it is an SVG, a simple <img/> is rendered.

Empty state

If src is null/undefined or cannot be resolved, the component renders an EmptyImage placeholder. You can customize its content:

<RasterImage
  alt="Missing"
  src={null}
  width={200}
  height={150}
  noImageContent={<span>No image</span>}
/>

Props

export type RasterImageProps = {
  alt: string;                              // Required alt text for accessibility
  breakpoints?: Record<string, string>;     // Named breakpoints -> media queries used by `<source/>`
  className?: string;                       // Wrapper `<picture/>` class
  heights?: number[];                       // Candidate heights for responsive sources
  imgClassName?: string;                    // `<img/>` element class
  loading?: ImgHTMLAttributes<HTMLImageElement>["loading"]; // "lazy" | "eager"
  mode?: "contain" | "cover" | "responsive"; // Adds CSS helper classes
  noImageContent?: React.ReactNode;         // Custom placeholder content when no image
  options?: ImageSourcesOptions;            // Resizer/source generation options (passed through)
  quality?: Quality;                        // Preferred quality; defaults to original if not specified
  role?: ImgHTMLAttributes<HTMLImageElement>["role"];       // Optional ARIA role override
  src: ImageSource | null | undefined;      // Image source compatible with @uxf/core/utils/resizer
  widths?: number[];                        // Candidate widths for responsive sources
} & (
  | { width: number; height: number }
  | { width?: never; height: number }
  | { width: number; height?: never }
);

Sizing behavior

• The fallback <img/> receives width/height computed via getImgElementWidth/Height based on your provided width/height and the intrinsic ratio when available.
• When both width and height are omitted, TypeScript will error by design (you must provide at least one dimension).

Quality and options

• quality controls the requested resizer quality; when omitted, the component uses getImgQuality(..., "original").
• options are passed to the underlying resizer/source helpers. See @uxf/core/utils/resizer and ImageSourcesOptions for details.

Accessibility

• alt is required. Use an empty string ("") only for purely decorative images.
• role is rarely needed; rely on native img semantics where possible.
• Consider loading="lazy" for below-the-fold images to improve performance.

Styling

Wrapper and image classes you can target:

• Wrapper <picture/>: "uxf-raster-image"
  • Modifiers: "uxf-raster-image--contain", "uxf-raster-image--cover"
• <img/>: "uxf-raster-image__img"
  • Modifiers: "uxf-raster-image__img--contain", "uxf-raster-image__img--cover"

You can also pass className and imgClassName to append your own classes.

SVG handling

If getSvgImgUrl(src) returns a URL, the component renders a plain <img src="...svg"/> inside <picture/>, bypassing the resizer.

Notes on integration with the resizer

• resizerImageUrl is used to produce the fallback <img/> source when possible.
• Responsive <source/> tags are produced by ResponsiveImgSources using widths/heights and breakpoints.
• If resizerSrc cannot be generated, the component falls back to the EmptyImage placeholder.