bloomImage function

BloomNode bloomImage({
  1. required String src,
  2. String? alt,
  3. bool decorative = false,
  4. int? width,
  5. int? height,
  6. String? aspectRatio,
  7. List<int>? widths,
  8. String? sizes,
  9. ImageUrlBuilder? urlBuilder,
  10. ImageLoading loading = ImageLoading.lazy,
  11. ImageDecoding decoding = ImageDecoding.async,
  12. FetchPriority? fetchPriority,
  13. bool priority = false,
  14. String? placeholder,
  15. String? fallbackSrc,
  16. ImageFit? fit,
  17. String? className,
  18. String? style,
  19. Map<String, String>? attrs,
  20. BloomEventHandler? onClick,
  21. BloomEventHandler? onLoad,
  22. BloomEventHandler? onError,
  23. Ref<Object>? ref,
})

High-performance responsive image descriptor helper for Bloom JS Native.

Composes a standard <img> element with performance and accessibility best practices:

  • Responsive sources: Generates srcset and sizes automatically from widths and urlBuilder.
  • Lazy loading by default: Defaults to ImageLoading.lazy and ImageDecoding.async to avoid wasting network bandwidth and main-thread CPU cycles on offscreen images during initial load.
  • LCP Hero Image Optimization: Pass priority: true for above-the-fold hero images. This emits loading="eager", fetchpriority="high", and decoding="async", preventing the delayed Largest Contentful Paint (LCP) penalty caused by lazy-loading hero content.
  • Layout stability (CLS): Providing width and height (or CSS aspectRatio) reserves the correct layout box before image bytes arrive over the network, preventing Cumulative Layout Shift (CLS).
  • Placeholders: Supports solid CSS colors (e.g. '#14141a') or data URIs / blurhash URLs rendered immediately as background styles in SSR and client DOM.
  • Accessibility: Explicitly specify alt text describing the image, or set decorative: true to emit alt="" and aria-hidden="true" for presentational visuals.

SSR and Browser Compatibility

Pure Dart descriptor. During SSR (renderToHtml), it renders a sanitized HTML5 <img> string with attributes and inline placeholder styles. In the browser DOM (mount), it instantiates an HTMLImageElement, binds event handlers (onLoad, onError, onClick), and attaches ref.

bloomImage(
  src: '/assets/product.jpg',
  alt: 'Wireless Noise-Canceling Headphones',
  width: 800,
  height: 600,
  widths: [400, 800, 1200],
  sizes: '(max-width: 600px) 100vw, 800px',
  placeholder: '#14141a',
  fit: ImageFit.cover,
);

See also:

Implementation

BloomNode bloomImage({
  required String src,
  String? alt,
  bool decorative = false,
  int? width,
  int? height,
  String? aspectRatio,
  List<int>? widths,
  String? sizes,
  ImageUrlBuilder? urlBuilder,
  ImageLoading loading = ImageLoading.lazy,
  ImageDecoding decoding = ImageDecoding.async,
  FetchPriority? fetchPriority,
  bool priority = false,
  String? placeholder,
  String? fallbackSrc,
  ImageFit? fit,
  String? className,
  String? style,
  Map<String, String>? attrs,
  BloomEventHandler? onClick,
  BloomEventHandler? onLoad,
  BloomEventHandler? onError,
  Ref<Object>? ref,
}) {
  return BloomImage(
    src: src,
    alt: alt,
    decorative: decorative,
    width: width,
    height: height,
    aspectRatio: aspectRatio,
    widths: widths,
    sizes: sizes,
    urlBuilder: urlBuilder,
    loading: loading,
    decoding: decoding,
    fetchPriority: fetchPriority,
    priority: priority,
    placeholder: placeholder,
    fallbackSrc: fallbackSrc,
    fit: fit,
    className: className,
    style: style,
    attrs: attrs,
    onClick: onClick,
    onLoad: onLoad,
    onError: onError,
    ref: ref,
  );
}