ran
English

Image

Image component that renders an image with a built-in fallback shown when the source fails to load.

Use when you need an image that gracefully degrades to a placeholder if the source fails to load: <r-img> swaps in a built-in broken-image graphic or your own fallback.

Quick Start

Basic Usage

<r-img src="https://picsum.photos/id/1015/240/160"></r-img>

API Reference

Properties

Property Type Default Description
src string '' Image source URL. Reactive: changing it after mount reloads the image.
alt string '' Alternative text forwarded to the inner <img>. Empty marks it as decorative.
fallback string built-in broken-image data URI Image shown when src fails to load.
sheet string '' CSS injected into the component's shadow DOM.

src, alt, fallback, and sheet are all observed and update reactively: changing any of them on a mounted element takes effect immediately.

Image Source src

<r-img src="https://picsum.photos/id/1025/240/160"></r-img>

Alternative Text alt

alt is forwarded to the inner <img>. Leave it empty (the default) for decorative images so screen readers skip them; provide a description for meaningful images.

<r-img src="https://picsum.photos/id/1035/240/160" alt="A mountain lake at dusk"></r-img>

Load Failure fallback

When src fails to load, the component swaps in fallback. If fallback is not set, a built-in broken-image placeholder is used. Below, src is an invalid URL, so the fallback image is shown instead.

<r-img
  src="https://example.invalid/does-not-exist.png"
  fallback="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...(broken image placeholder)..."
></r-img>

External Styles sheet

sheet injects raw CSS into the component's shadow DOM. Use it to style the internal .ran-image container or the inner <img>.

<r-img
  src="https://picsum.photos/id/1043/240/160"
  sheet="img { border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,.25); }"
></r-img>

Events

None. r-img does not dispatch any custom events.

Best Practices

  • Change src anytime: src is reactive, so updating it on a mounted element reloads the image; the fallback still kicks in if the new URL fails to load.
  • Provide alt for meaningful images: Describe the content for screen readers; leave alt empty only for purely decorative images.
  • Rely on the built-in fallback: A default broken-image placeholder is used automatically, but supply your own fallback when you want a branded or context-appropriate placeholder.
  • Style with sheet: Since the image lives in shadow DOM, use the sheet attribute (or component CSS variables) to apply borders, radius, or sizing.