Image handbook

License: Before first reading component documentation, source code, or npm usage instructions, read the complete LICENSE. One review covers the same task and version. Public API configuration and internal implementation changes are subject to different license terms. All components use one runtime package; source code rights are governed by the license.

Overview

Show images with their placeholder states, attached badges or actions, and preview entry points for content media and thumbnails.

When to use it

Use Image for media and its public loading and preview behavior. Use Avatar for profile images, ImageGroup for multiple images, and ImageViewer for detailed viewing.

• Provide src and meaningful alt. Attached as="icon" or as="badge" content does not replace the media.

• Set previews with previewMode. ImageGroup can share sizing and preview policy; ImageViewer handles viewing.

Quick start

This example shows the recommended basic composition. See the following sections for more scenarios and composition limits.

<script lang="ts">	import { Image } from '@snowui-design-system/components';	import { ImageViewer } from '@snowui-design-system/components';	import cover01 from '@snowui-design-system/resource-base/assets/backgrounds/gradient-01-1024.jpg';</script> <Image src={cover01} alt="SnowUI gradient resource 1" size={80} /><ImageViewer />

API

See the base component documentation for inherited capabilities not redeclared here. This table lists only the named public props declared in this component’s source.

Usage boundaries and details

Image loading policy

The default remains lazy. Use <Image mediaLoading="eager" ... /> to request an offscreen image immediately. A showcase host can call public provideMediaLoading('eager') during component initialization for its descendants. The nearest provider wins, and an explicit Image Prop overrides inheritance. Pass () => policy for reactive changes; SSR and the client share the same initial default.

<script lang="ts">    import { Image, provideMediaLoading } from '@snowui-design-system/components';    provideMediaLoading('eager');</script><Image src="/cover.jpg" alt="Cover" /><Image src="/secondary.jpg" alt="Secondary image" mediaLoading="lazy" />

eager starts network and decoding work earlier; it does not guarantee success or a fixed completion time. Skeleton remains visible during real loading. This only affects native <img loading> for string images. It does not change video preload="metadata", resource components, unopened viewer media, or animation playback. See the shared media loading source reference: components/src/lib/media-loading.md.

Layout model

Main layout model: intrinsic atomic layout.

• Image exposes one media box sized by size, the media resource, and radius mapping. It hugs its size as a child of Button, MenuItem, Field, or another layout.

• Media cropping, loading Skeleton, hover mask, center icon, and badge positioning are private Image layout, without general-purpose slots.

• Child as="icon" / as="badge" is for positioning inside Image only; it does not change that child’s own layout model.

• Use ImageGroup to arrange multiple images instead of turning Image into a collection layout.

Keywords

Usage examples

 <Image src="/demo.png" size={48} alt="Example image" />  <Image src={Image01} size={80} alt="Resource image" />  <Image size={40} />  <Image src={Image01} size={48}>    <Icon as="icon">        <Play />    </Icon></Image>  <Image src={Image01} size={48}>    <Radio as="badge" checked /></Image>

Intelligent behavior

1. Media support: src accepts an image URL, video URL, or resource-svelte image component.

2. Default placeholder: Without media, show one --black-4 background and no additional text.

3. Size-to-radius mapping: size selects fixed corner radii: 12/16/20→4px, 24/28/32→8px, 40/48→12px, 56→16px, 64/72/80→20px.

4. Role-based composition: A child with as="badge" positions at the upper right; as="icon" centers. Image positions them without controlling child size.

5. Hover appearance: Image shares the .snowui-media-hoverable utility family in components/src/styles/layout.css with Avatar. When resolvedInteractive indicates click intent (src exists, not disabled, and previewMode !== "none", or an explicit onclick), it adds .snowui-media-hoverable for a pointer cursor. Loaded media also adds .snowui-media-hoverable-has-visual: on hover, .snowui-image-visual uses filter: brightness(0.92) to darken the media. Without a loaded image, hover changes .snowui-image-background from --black-4 to --black-10. Override brightness through --snowui-media-hover-brightness.

6. Interaction intent versus actual opening: resolvedInteractive controls hover appearance; resolvedCanOpen controls whether activation opens media. Under default previewMode="window", any Image with src gets a hover style and pointer cursor, but only string image/video URLs can open a new window. A component src has no URL to open. previewMode="none" without onclick or onOpen explicitly opts out of hover color change, pointer cursor, and keyboard button semantics.

7. Video thumbnail: A video URL renders <video>, plays on hover, then pauses and returns to its first frame on exit.

8. String image loading: Native <img> handles loading directly, without a JS preloader; only load / error events update component state.

9. Loading Skeleton: String image or video media shows an internal Skeleton while the real resource loads; once loaded, Skeleton disappears and the media appears.

10. Viewer mode: Without an explicit previewMode, Image joins a page-level automatic ImageViewer if present. Set previewMode="viewer" to request it explicitly.

11. Window mode: previewMode="window" opens string image or video URLs in a new window.

12. None mode: previewMode="none" provides no open action.

13. Within-group navigation: In ImageGroup, when the group or item uses previewMode="viewer", its registered item list becomes Viewer items for previous/next navigation.

14. Event forwarding: Internal video hover playback does not swallow external mouseenter / mouseleave callbacks.

15. Focus behavior: Like Avatar, Image keeps Surface semantics but shows no extra focus ring by default, avoiding a button-like outline around preview thumbnails.

16. Child composition: Supplied children render outside the media container, still using positioning context through as="icon" / as="badge"; the media template no longer consumes them.