Struct Image

pub struct Image { /* private fields */ }

Available on crate feature yew only.

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.

See Also

• MDN img Element

Trait Implementations

impl BaseComponent for Image

where Self: 'static,

type Message = ()

The Component’s Message.

type Properties = ImageProps

The Component’s Properties.

fn create(ctx: &Context<Self>) -> Self

Creates a component.

fn update(&mut self, _ctx: &Context<Self>, _msg: Self::Message) -> bool

Updates component’s internal state.

fn changed( &mut self, _ctx: &Context<Self>, _old_props: &Self::Properties, ) -> bool

React to changes of component properties.

fn view(&self, ctx: &Context<Self>) -> HtmlResult

Returns a component layout to be rendered.

fn rendered(&mut self, _ctx: &Context<Self>, _first_render: bool)

Notified after a layout is rendered.

fn destroy(&mut self, _ctx: &Context<Self>)

Notified before a component is destroyed.

fn prepare_state(&self) -> Option<String>

Prepares the server-side state.

impl Debug for Image

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FunctionProvider for Image

type Properties = ImageProps

Properties for the Function Component.

fn run(ctx: &mut HookContext, props: &Self::Properties) -> HtmlResult

Render the component. This function returns the Html to be rendered for the component.