Struct Image

Source

pub struct Image { /* private fields */ }

Available on crate feature yew only.

Expand description

Image Component

A highly optimized and feature-rich Image component for Yew applications, supporting lazy loading, blur placeholders, fallback handling, and multiple responsive layouts.

§Properties

The component uses the ImageProps struct for its properties. Key properties include:

src: The main image source URL (&'static str). Required.
alt: Alternative text for accessibility (&'static str). Default: "".
layout: The image layout strategy (Layout). Default: Layout::Auto.
width: The width of the image (&'static str). Required for certain layouts.
height: The height of the image (&'static str). Required for certain layouts.
sizes: Defines responsive image sizes (&'static str). Default: "".
quality: Image quality (custom property) (&'static str). Optional.
placeholder: Placeholder strategy before the image loads (e.g., "blur") (&'static str). Default: "".
blur_data_url: Base64-encoded low-res placeholder image (&'static str). Used when placeholder is "blur".
fallback_src: Fallback image URL if the main src fails to load (&'static str). Optional.
priority: Whether to load the image eagerly instead of lazily (bool). Default: false.
object_fit: CSS object-fit value (ObjectFit). Default: ObjectFit::Contain.
object_position: Object positioning inside the container (Position). Default: Position::Center.
style: Additional inline CSS styles (&'static str). Default: "".
class: Additional CSS classes (&'static str). Default: "".
decoding: Decoding strategy (Decoding). Default: Decoding::Auto.
on_load: Callback invoked when the image successfully loads (Callback<()>). Default: no-op.
on_error: Callback invoked if loading or fallback loading fails (Callback<String>). Default: no-op.
node_ref: Node reference for the underlying img element (NodeRef).
ARIA attributes: Full ARIA support for better accessibility (aria_label, aria_hidden, etc.).

§Features

Lazy Loading with IntersectionObserver: Image is loaded only when scrolled into view, boosting performance and saving bandwidth.
Fallback Handling: Automatically tries a fallback_src if the primary src fails, ensuring robustness.
Blur Placeholder: Supports blurred low-resolution placeholders for smoother image transitions.
Multiple Layouts: Supports various layouts like Fill, Responsive, Intrinsic, Fixed, Auto, Stretch, and ScaleDown.
Accessibility: Built-in support for ARIA attributes to make images fully accessible.

§Layout Modes

Layout::Fill: Image stretches to fill its container absolutely.
Layout::Responsive: Maintains aspect ratio and scales responsively.
Layout::Intrinsic: Renders using natural image dimensions.
Layout::Fixed: Renders at a fixed size.
Layout::Auto: Default natural behavior without forcing constraints.
Layout::Stretch: Fills the parent container’s width and height.
Layout::ScaleDown: Scales image down to fit the container without stretching.

§Examples

§Basic Usage

use yew::prelude::*;
use image_rs::yew::Image;
use image_rs::Layout;

#[function_component(App)]
pub fn app() -> Html {
    html! {
        <Image
            src="/images/photo.jpg"
            alt="A beautiful view"
            width="800"
            height="600"
            layout={Layout::Responsive}
        />
    }
}

§Blur Placeholder

use yew::prelude::*;
use image_rs::yew::Image;
use image_rs::Layout;

#[function_component(App)]
pub fn app() -> Html {
    html! {
        <Image
            src="/images/photo.jpg"
            alt="Blur example"
            width="800"
            height="600"
            layout={Layout::Intrinsic}
            placeholder="blur"
            blur_data_url="data:image/jpeg;base64,..."
        />
    }
}

§Fallback Image

use yew::prelude::*;
use image_rs::yew::Image;
use image_rs::Layout;

#[function_component(App)]
pub fn app() -> Html {
    html! {
        <Image
            src="/images/main.jpg"
            fallback_src="/images/fallback.jpg"
            alt="With fallback"
            width="800"
            height="600"
            layout={Layout::Fixed}
        />
    }
}

§Behavior

The image starts loading lazily once it enters the viewport (10% visible threshold).
If loading fails, a network fetch checks the fallback image.
Blur placeholder is rendered with a heavy blur(20px) effect until the full image loads.
Depending on the Layout, the container styling adjusts automatically.

§Notes

width and height are required for Responsive, Intrinsic, and Fixed layouts.
Layout::Fill ignores width and height, stretching to fit the parent container.
Accessibility attributes like aria-label and aria-hidden are passed directly to the <img> element.
Priority images (priority = true) are loaded eagerly instead of lazily.

§Errors

If both src and fallback_src fail, the on_error callback is triggered with an error message.
JSON parsing from a fallback response is attempted but not mandatory for image loading success.

§Optimization Techniques

IntersectionObserver is used for intelligent lazy loading.
Caching via RequestCache::Reload ensures fallback images are always fetched fresh if needed.
Async/await approach for fetch operations provides non-blocking fallback handling.