Image RS

Y Image RS Yew Usage

Adding Image RS to your project is simple:

Make sure your project is set up with Yew. Follow their Getting Started Guide for setup instructions.
Add the Image RS component to your dependencies by including it in your Cargo.toml file:
```
cargo add image-rs --features=yew
```
Import the Image component into your Yew component and start using it in your app.

🛠️ Usage

Incorporating Image RS into your Yew application is easy. Follow these steps:

Import the Image component into your Yew project:

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

Use the Image component within your Yew application:

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}
        />
    }
}

🔧 Props

🖼️ Main Props

Property	Type	Description	Default
`src`	`&'static str`	The image source URL.	`""`
`alt`	`&'static str`	Alt text for accessibility.	`"Image"`
`fallback_src`	`&'static str`	Image shown if the primary source fails.	`""`
`width`	`&'static str`	Width in pixels.	`""`
`height`	`&'static str`	Height in pixels.	`""`
`layout`	`Layout`	Layout type: `Responsive`, `Fixed`, etc.	`Responsive`
`placeholder`	`&'static str`	Placeholder image while loading.	`"empty"`
`loading`	`Loading`	`Lazy` or `Eager` loading strategy.	`Lazy`
`priority`	`bool`	(Deprecated) Use `loading = Eager` instead.	`false`

🎨 Styling Props

+-----------------------------------------------------------+
|                  [Image Container]                        |  <-- `class` & `style`
|                                                           |
|   +-----------------------------------------------+       |  <-- `layout`
|   |              [Loaded Image]                   |       |  <-- `src`
|   +-----------------------------------------------+       |
|                                                           |
+-----------------------------------------------------------+

Property	Type	Description	Default
`style`	`&'static str`	Inline CSS styles.	`""`
`class`	`&'static str`	CSS class name(s).	`""`
`object_fit`	`ObjectFit`	How the image fits: `Contain`, `Cover`, `Fill`, etc.	`Contain`
`object_position`	`Position`	Image position inside container (e.g., `TopRight`).	`Center`
`sizes`	`&'static str`	Defines image sizes for responsive rendering.	`""`
`quality`	`&'static str`	Image quality hint (`"low"`, `"high"`).	`""`
`blur_data_url`	`&'static str`	Low-quality blur-up image while loading.	`""`

⚙️ Behavioral Props

Property	Type	Description	Default
`on_load`	`Callback<()>`	Triggered when image finishes loading.	No-op
`on_error`	`Callback<String>`	Triggered if the image fails to load.	No-op
`decoding`	`Decoding`	Controls image decode strategy: `Auto`, `Sync`, `Async`	`Auto`

🌐 Network & Source Props

Property	Type	Description	Default
`srcset`	`&'static str`	Comma-separated list of responsive image sources.	`""`
`crossorigin`	`CrossOrigin`	CORS policy (`Anonymous`, `UseCredentials`).	`CrossOrigin::None`
`referrerpolicy`	`ReferrerPolicy`	Referrer policy for requests.	`NoReferrer`
`usemap`	`&'static str`	Associates the image with a `<map>` by ID.	`""`
`ismap`	`bool`	Enables server-side image maps (inside `<a href>`).	`false`

⚡ Performance Props

Property	Type	Description	Default
`fetchpriority`	`FetchPriority`	Network priority (`High`, `Low`, `Auto`).	`Auto`
`elementtiming`	`&'static str`	Marks image with ID for `PerformanceElementTiming`.	`""`
`attributionsrc`	`&'static str`	URL for Attribution Reporting (experimental).	`""`
`lazy_boundary`	`&'static str`	Distance from viewport to trigger lazy load (e.g. `200px`).	`"100px"`
`unoptimized`	`bool`	Disables built-in image optimization.	`false`

🧠 Accessibility Props (ARIA)

Property	Type	Description	Default
`aria_current`	`&'static str`	Indicates the current step/page (`"page"`, `"step"`, etc).	`""`
`aria_describedby`	`&'static str`	ID of an element describing the image.	`""`
`aria_expanded`	`&'static str`	`"true"` or `"false"` for expanded/collapsed state.	`""`
`aria_hidden`	`&'static str`	Hides image from assistive tech (`"true"` or `"false"`).	`"false"`
`aria_live`	`AriaLive`	Dynamic update priority (`Off`, `Polite`, `Assertive`).	`Off`
`aria_pressed`	`AriaPressed`	Indicates toggle state (`True`, `False`, `Mixed`, or `Undefined`).	`False`
`aria_controls`	`&'static str`	ID of the element that the image controls.	`""`
`aria_labelledby`	`&'static str`	ID of the label element for the image.	`""`

🧱 Utility

Property	Type	Description	Default
`node_ref`	`NodeRef`	Reference to the DOM image element for JS interop or tracking.	Default

💡 Notes

The src and alt attributes are required for basic functionality.
The width and height are essential for Responsive, Intrinsic, and Fixed layouts.
Use the placeholder and blur_data_url properties for a smoother loading experience.
Customize the appearance and behavior using class, style, and other props like layout and object_fit.
Callbacks like on_load and on_error allow you to handle the image loading process effectively.
The Layout::Fill value ignores the width and height props and stretches to fill the container.
Accessibility attributes like aria-label and aria-hidden can be used directly on the image element.
Priority images (priority = true) are loaded eagerly rather than lazily.
If both src and fallback_src fail, the on_error callback is triggered with an error message.
blur_data_url is used for rendering a low-quality blurred image while the full image loads.
IntersectionObserver: This is used for intelligent lazy loading of images as they enter the viewport.
Async/Await: Fetch operations use non-blocking async/await for smoother fallback handling.

📈 Benchmark

Open browser DevTools (Press F12) > Lighthouse tab.
Record page load by clicking "Analyze Page Load".
Observe:
- First Contentful Paint (FCP)
- Largest Contentful Paint (LCP)
- Time to Interactive (TTI)
- Total network transfer size
- Memory usage

🚀 Summary

Feature	Yew Image RS	Next.js Image
Native Rust+Wasm	✅	❌
Built-in Image Optimization	✅	✅
SSR/SEO Friendly	✅	✅
Fine-grained DOM Control	✅	❌
Smaller JS Payload	✅	✅

📊 Performance Results

When loading 10 images, Yew Image RS and Next.js Image are on par:

Metric	Yew (Wasm)	Next.js
Performance Score (Lighthouse)	100	100
Memory Usage (Heap)	~8 MB	~8 MB

However, when scaling up to 10,000 images loaded simultaneously:

Metric	Yew (Wasm)	Next.js
Performance Score (Lighthouse)	64	❌ (Lighthouse fails)
Memory Usage (Heap)	~78 MB	~83 MB
Scrolling Smoothness	Very Smooth	Laggy

Key observations:

Wasm (Yew) handles large DOM updates much better than JavaScript.
Memory usage is slightly lower with Wasm.
Next.js site failed Lighthouse audit at 10,000 images (due to TTI timeout).
Smoothness is significantly better with Yew under heavy load.

🛠️ Future Improvements

Image RS is working on automatic image optimization.
Progressive loading and lazy hydration strategies are being researched for even better large-scale performance.

Usage

CLI Usage

You can import Image RS directly into your project to customize and modify it using the opensass cli:

os add image-rs yew

Edit Component

🧬 Image RS Dioxus Usage

Adding Image RS to your project is simple:

Make sure your project is set up with Dioxus. Refer to the Dioxus Getting Started Guide for setup instructions.
Add the image-rs library to your dependencies by including it in your Cargo.toml file:
```
cargo add image-rs --features=dio
```
Import the Image component into your Dioxus application.

🛠️ Usage

Incorporating Image RS into your Dioxus application is simple. Here's how:

Add the Image component to your Dioxus project:

use dioxus::prelude::*;
use image_rs::dioxus::Image;

Use the Image component in your app like this:

use dioxus::prelude::*;
use image_rs::dioxus::Image;
use image_rs::{Layout, Loading};

fn App() -> Element {
    rsx! {
        Image {
            src: "/images/photo.jpg",
            alt: "A beautiful view",
            width: "800",
            height: "600",
            layout: Layout::Responsive,
            loading: Loading::Lazy,
        }
    }
}

🔧 Props

🖼️ Main Props

Property	Type	Description	Default
`src`	`&'static str`	Image source path or URL	`""`
`alt`	`&'static str`	Alt text for accessibility	`"Image"`
`fallback_src`	`&'static str`	Fallback image if `src` fails	`""`
`width`	`&'static str`	Width in pixels	`""`
`height`	`&'static str`	Height in pixels	`""`
`layout`	`Layout`	Layout strategy: Responsive, Fill, etc.	`Responsive`
`placeholder`	`&'static str`	Placeholder while loading	`"empty"`
`loading`	`Loading`	Load strategy: `Lazy` or `Eager`	`Lazy`

🎨 Styling Props

+-----------------------------------------------------------+
|                  [Image Container]                        |  <-- `class` & `style`
|                                                           |
|   +-----------------------------------------------+       |  <-- `layout`
|   |              [Loaded Image]                   |       |  <-- `src`
|   +-----------------------------------------------+       |
|                                                           |
+-----------------------------------------------------------+

Property	Type	Description	Default
`class`	`&'static str`	CSS classes	`""`
`style`	`&'static str`	Inline CSS styles	`""`
`object_fit`	`ObjectFit`	Resizing mode: `Cover`, `Contain`, etc.	`Contain`
`object_position`	`Position`	Alignment inside container	`Center`
`sizes`	`&'static str`	Responsive image size hints	`""`
`quality`	`&'static str`	Image quality hint	`""`
`blur_data_url`	`&'static str`	Low-res blurred image to show while loading	`""`

⚙️ Behavioral Props

Property	Type	Description	Default
`on_load`	`Callback<()>`	Called when image has loaded	No-op
`on_error`	`Callback<String>`	Called when image fails to load	No-op
`decoding`	`Decoding`	Image decoding strategy: Auto, Sync, Async	`Auto`

🌐 Network & Source Props

Property	Type	Description	Default
`srcset`	`&'static str`	Set of image sources for responsive behavior	`""`
`crossorigin`	`CrossOrigin`	CORS mode	`None`
`referrerpolicy`	`ReferrerPolicy`	Controls how much referrer info is sent	`NoReferrer`
`usemap`	`&'static str`	Use with image maps	`""`
`ismap`	`bool`	Server-side image maps inside `<a>` tags	`false`

⚡ Performance Props

Property	Type	Description	Default
`fetchpriority`	`FetchPriority`	Image fetch priority (`Auto`, `High`, `Low`)	`Auto`
`elementtiming`	`&'static str`	Performance marker ID	`""`
`attributionsrc`	`&'static str`	Attribution reporting URL (experimental)	`""`
`lazy_boundary`	`&'static str`	How early to trigger lazy load (`e.g., "200px"`)	`"100px"`
`unoptimized`	`bool`	Disables automatic image optimizations	`false`

🧠 Accessibility Props (ARIA)

Property	Type	Description	Default
`aria_current`	`&'static str`	Current step/item indicator (`"page"`, `"step"`, etc.)	`""`
`aria_describedby`	`&'static str`	ID of an element describing the image	`""`
`aria_expanded`	`&'static str`	`"true"` or `"false"` if content is expanded	`""`
`aria_hidden`	`&'static str`	Hides image from assistive tech	`"false"`
`aria_live`	`AriaLive`	Priority of live region updates (`Off`, `Polite`, `Assertive`)	`Off`
`aria_pressed`	`AriaPressed`	Toggle state (`True`, `False`, `Mixed`, `Undefined`)	`False`
`aria_controls`	`&'static str`	ID of element this image controls	`""`
`aria_labelledby`	`&'static str`	ID of label element	`""`

💡 Notes

Required: src and alt are essential for accessibility and rendering.
Layout behavior:
- Responsive, Fill, Intrinsic, and Fixed alter how dimensions are applied.
- Fill ignores width/height and stretches the image.
Loading:
- placeholder and blur_data_url create a smoother user experience.
- Use on_load / on_error for lifecycle management.
Lazy loading:
- Uses IntersectionObserver.
- lazy_boundary controls how early the image loads.
Optimization:
- unoptimized = true disables default optimizations.
Performance tracking:
- elementtiming and attributionsrc assist in analytics and attribution.
Accessibility:
- Add aria-* attributes to enhance usability with screen readers and assistive devices.

Usage

CLI Usage

You can import Image RS directly into your project to customize and modify it using the opensass cli:

os add image-rs dio

Edit Component

🌱 Leptos Image RS Usage

Adding Image RS to your Leptos project is simple:

Make sure your project is set up with Leptos. Refer to their Getting Started Guide for setup instructions.
Add image-rs to your dependencies:
```
cargo add image-rs --features=lep
```
Import the Image component into your Leptos component and start using it in your app.

🛠️ Usage

Incorporating the Image component into your Leptos application is easy. Here's a basic example:

use leptos::{*, prelude::*};
use image_rs::leptos::Image;
use image_rs::Layout;
use leptos::logging::log;

#[component]
pub fn App() -> impl IntoView {
    view! {
        <Image
            src="https://example.com/image.jpg"
            alt="An example image"
            width="600"
            height="400"
            layout=Layout::Responsive
            class="my-image"
            style="border-radius: 8px;"
            placeholder="blur"
            blur_data_url="data:image/png;base64,..."
            fallback_src="https://example.com/fallback.jpg"
            on_load=Callback::new(|_| log!("Image loaded successfully"))
            on_error=Callback::new(|err| log!("Image failed: {err}"))
        />
    }
}

🔧 Props

`Image` Props

Main Props

Property	Type	Description	Default
`src`	`&'static str`	The URL of the image to be displayed.	`""`
`alt`	`&'static str`	Alt text for accessibility and SEO.	`"Image"`
`fallback_src`	`&'static str`	URL for the fallback image in case of error.	`""`
`width`	`&'static str`	The width of the image.	`""`
`height`	`&'static str`	The height of the image.	`""`
`layout`	`Layout`	Image layout: `Fill`, `Responsive`, or `Intrinsic`.	`Responsive`

Loading & Placeholder Props

Property	Type	Description	Default
`loading`	`Loading`	Image loading behavior: `Eager` or `Lazy`.	`Lazy`
`placeholder`	`&'static str`	Placeholder type: use `"blur"` for blurred placeholder.	`"empty"`
`blur_data_url`	`&'static str`	Base64-encoded data URL used when `placeholder="blur"`.	`""`

Styling Props

Property	Type	Description	Default
`class`	`&'static str`	CSS class for the `<img>` element.	`""`
`style`	`&'static str`	Additional inline styles.	`""`
`object_fit`	`ObjectFit`	How the image should fit within its box.	`Fill`
`object_position`	`Position`	Image alignment inside the container.	`Center`
`sizes`	`&'static str`	Sizes attribute for responsive images.	`""`
`srcset`	`&'static str`	Srcset for responsive image variants.	`""`

Event Callbacks

Property	Type	Description
`on_load`	`Option<Callback<()>>`	Triggered when the image successfully loads.
`on_error`	`Option<Callback<String>>`	Triggered when the image fails to load.

Advanced Browser Attributes

Property	Type	Description	Default
`decoding`	`Decoding`	How the browser should decode the image.	`Auto`
`crossorigin`	`CrossOrigin`	CORS behavior for the image.	`None`
`referrerpolicy`	`ReferrerPolicy`	Referrer policy for the request.	`NoReferrer`
`fetchpriority`	`FetchPriority`	Priority for fetching the image.	`Auto`

Accessibility Props

Property	Type	Description	Default
`aria_current`	`&'static str`	ARIA current attribute	`""`
`aria_describedby`	`&'static str`	ARIA description	`""`
`aria_expanded`	`&'static str`	ARIA expanded attribute	`""`
`aria_hidden`	`&'static str`	Whether the image is hidden from assistive technologies.	`""`
`aria_live`	`AriaLive`	ARIA live region setting.	`Off`
`aria_pressed`	`AriaPressed`	ARIA pressed state.	`Undefined`
`aria_controls`	`&'static str`	ID of the element that this controls.	`""`
`aria_labelledby`	`&'static str`	ID of the element that labels this image.	`""`

Other Props

Property	Type	Description	Default
`node_ref`	`NodeRef<Img>`	Reference to the `<img>` DOM element.	`None`
`usemap`	`&'static str`	HTML `usemap` attribute value.	`""`
`ismap`	`bool`	Indicates if the image is part of a server-side map.	`false`
`elementtiming`	`&'static str`	Used for performance reporting (e.g., LCP).	`""`
`attributionsrc`	`&'static str`	Attribution source for content licensing.	`""`

💡 Notes

The Image component is flexible for layout use cases: use Fill to cover parent, or Responsive to maintain aspect ratio.
Use the placeholder="blur" and blur_data_url to provide a low-res preview while loading.
Fallback logic automatically switches to fallback_src if the main image fails to load.
All ARIA attributes and semantic accessibility features are built-in and customizable.
The component supports lazy loading by default with loading=Loading::Lazy.

Usage

CLI Usage

You can import Image RS directly into your project to customize and modify it using the opensass cli:

os add image-rs lep

Open SASS Components Kit