Image and Icon: Rendering Media and SVG Icon Assets

Image and Icon are the two media display primitives in Compose Svelted. Image renders any raster or vector graphic with configurable object-fit scaling behavior. Icon uses CSS masking to render SVG files as a monochrome shape tinted by any ColorToken or CSS color — the same technique used in Material 3 icon systems.

Image

Image wraps an <img> element inside a clipping <div>. Size and position are controlled by Modifier, and the fit behavior is set through ContentScale tokens.

Props

painter

string

default:"\"\""

URL of the image to display. Use painterResource() for assets bundled with your project, or any absolute/relative URL for external images.

contentScale

ContentScaleToken

default:"ContentScale.Fit"

How the image is scaled and cropped within its bounds. See ContentScale values below.

contentDescription

string

default:"\"\""

Accessible alt text for the rendered <img> element.

modifier

Modifier

default:"Modifier.empty()"

Controls the size and shape of the image container. Use Modifier.size(), Modifier.width(), or Modifier.height() to set explicit dimensions.

ContentScale values

ContentScale is a constant object that maps semantic scaling names to CSS object-fit values (with two special fill modes handled in JavaScript):

import { ContentScale } from '@danielito1996/compose-svelted';

ContentScale.Fit         // "contain"    — scale uniformly to fit; may letterbox
ContentScale.Crop        // "cover"      — scale uniformly to fill; may clip edges
ContentScale.FillBounds  // "fill"       — stretch to fill bounds; may distort
ContentScale.Inside      // "contain"    — same as Fit; never upscale beyond bounds
ContentScale.FillWidth   // "fillWidth"  — fill width, auto height; may clip vertically
ContentScale.FillHeight  // "fillHeight" — fill height, auto width; may clip horizontally
ContentScale.None        // "none"       — no scaling; renders at intrinsic size

Token	CSS behavior	Use when
`ContentScale.Fit`	`object-fit: contain`	Logo, illustration, or icon that must be fully visible
`ContentScale.Crop`	`object-fit: cover`	Hero images, avatars, thumbnails
`ContentScale.FillBounds`	`object-fit: fill`	Charts or diagrams that must match exact container
`ContentScale.Inside`	`object-fit: contain`	Same as `Fit`; useful for explicit intent
`ContentScale.FillWidth`	width 100%, height auto	Horizontal banner images
`ContentScale.FillHeight`	height 100%, width auto	Vertical strip images
`ContentScale.None`	`object-fit: none`	Pixel-art or images with fixed intrinsic sizes

Basic example

<script>
  import { Image, ContentScale, Modifier } from '@danielito1996/compose-svelted';
</script>

<!-- Fit within a fixed 200x200 container -->
<Image
  painter="https://example.com/photo.jpg"
  contentScale={ContentScale.Fit}
  contentDescription="A scenic mountain photo"
  modifier={Modifier.size(200)}
/>

Using painterResource

painterResource resolves a resource name to /assets/{resourceName}, mapping to the public/assets/ folder of your project.

<script>
  import {
    Image, ContentScale, Modifier,
    painterResource, Res
  } from '@danielito1996/compose-svelted';
</script>

<!-- Loads /assets/img/banner.png -->
<Image
  painter={painterResource(Res.image('banner.png'))}
  contentScale={ContentScale.Crop}
  contentDescription="Application banner"
  modifier={Modifier.fillMaxWidth().height(180)}
/>

Crop mode avatar

<script>
  import {
    Image, ContentScale, Modifier, RoundedCornerShape
  } from '@danielito1996/compose-svelted';
</script>

<Image
  painter="https://example.com/avatar.jpg"
  contentScale={ContentScale.Crop}
  contentDescription="User avatar"
  modifier={Modifier.size(56)}
/>

Icon

Icon renders a monochrome SVG icon using CSS masking. The SVG file is applied as a mask over a <div> whose background-color is set to the resolved tint color. This means the icon shape is always rendered as a solid, theme-aware color rather than the SVG’s own fill — making it trivial to adapt icons to any color role in the theme.

Props

painter

string

default:"\"\""

URL of the SVG icon file. Use painterResource(Res.raw(...)) for local SVG assets, or any public SVG URL.

tint

ColorToken | string | undefined

default:"undefined"

Icon color. Accepts a ColorToken, a raw CSS color string, or undefined.

When undefined or omitted: falls back to the onBackground theme token.
When a ColorToken string (e.g. "primary"): resolved through the active theme to var(--md-sys-color-primary).
When a raw CSS hex/RGB/HSL string: used directly without theme resolution.

modifier

Modifier

default:"Modifier.empty()"

Controls the icon container’s size and layout. Use Modifier.size(24) for standard 24 dp icons.

How CSS masking works

Internally, Icon sets:

-webkit-mask-image: url({painter});
mask-image: url({painter});
-webkit-mask-repeat: no-repeat;
mask-repeat: no-repeat;
-webkit-mask-size: contain;
mask-size: contain;
-webkit-mask-position: center;
mask-position: center;
background-color: {resolvedTint};

The SVG must use a single color (black recommended) for the mask to work correctly. Multi-color SVGs will lose their color information.

Basic example

<script>
  import {
    Icon, Modifier, ColorScheme,
    painterResource, Res
  } from '@danielito1996/compose-svelted';
</script>

<!-- Icon tinted with the primary theme color -->
<Icon
  painter={painterResource(Res.raw('star.svg'))}
  tint={ColorScheme.Primary}
  modifier={Modifier.size(24)}
/>

Using a ColorToken

<script>
  import { Icon, Modifier, painterResource, Res } from '@danielito1996/compose-svelted';
</script>

<!-- Surface foreground color — adapts to light/dark theme automatically -->
<Icon
  painter={painterResource(Res.raw('home.svg'))}
  tint="onSurface"
  modifier={Modifier.size(24)}
/>

<!-- Error state icon -->
<Icon
  painter={painterResource(Res.raw('warning.svg'))}
  tint="error"
  modifier={Modifier.size(20)}
/>

Using a raw CSS color

<script>
  import { Icon, Modifier, painterResource, Res } from '@danielito1996/compose-svelted';
</script>

<Icon
  painter={painterResource(Res.raw('check.svg'))}
  tint="#4caf50"
  modifier={Modifier.size(24)}
/>

Using MDI SVG icon URLs

Material Design Icons (MDI) provides individual SVG files you can reference directly by URL:

<script>
  import { Icon, Modifier } from '@danielito1996/compose-svelted';

  const MDI_BASE = 'https://cdn.jsdelivr.net/npm/@mdi/[email protected]/svg';
</script>

<Icon
  painter={`${MDI_BASE}/account.svg`}
  tint="primary"
  modifier={Modifier.size(24)}
/>

<Icon
  painter={`${MDI_BASE}/magnify.svg`}
  tint="onSurface"
  modifier={Modifier.size(24)}
/>

painterResource helper

painterResource and Res are utility helpers that mirror the Jetpack Compose painterResource pattern for loading local assets.

`painterResource(resourceName)`

function painterResource(resourceName: string): string
// Returns: `/assets/${resourceName}`

Place your assets in the public/assets/ directory of your project. painterResource prepends /assets/ so the browser resolves the file correctly from the web root.

`Res` namespace

Res provides sub-folder helpers that produce path segments you pass into painterResource:

import { Res } from '@danielito1996/compose-svelted';

Res.raw('icon.svg')       // → "raw/icon.svg"      → /assets/raw/icon.svg
Res.image('banner.png')   // → "img/banner.png"     → /assets/img/banner.png
Res.values('theme.json')  // → "values/theme.json"  → /assets/values/theme.json
Res.fonts('Inter.woff2')  // → "fonts/Inter.woff2"  → /assets/fonts/Inter.woff2

Helper	Subfolder	Intended for
`Res.raw(fileName)`	`raw/`	SVG icons, raw files
`Res.image(fileName)`	`img/`	PNG, JPEG, WebP images
`Res.values(fileName)`	`values/`	JSON data files
`Res.fonts(fileName)`	`fonts/`	Font files

Example using Res helper

<script>
  import {
    Row, Image, Icon, Modifier,
    ContentScale, ColorScheme,
    painterResource, Res, Arrangement, Alignment
  } from '@danielito1996/compose-svelted';
</script>

<Row
  horizontalArrangement={Arrangement.spacedBy(16)}
  verticalAlignment={Alignment.CenterVertically}
>
  <!-- Raster image from /assets/img/avatar.png -->
  <Image
    painter={painterResource(Res.image('avatar.png'))}
    contentScale={ContentScale.Crop}
    contentDescription="User avatar"
    modifier={Modifier.size(80)}
  />

  <!-- SVG icon from /assets/raw/icon.svg -->
  <Icon
    painter={painterResource(Res.raw('icon.svg'))}
    tint={ColorScheme.OnBackground}
    modifier={Modifier.size(48)}
  />
</Row>

All files passed to painterResource must be present in your project’s public/assets/ directory at build time. The helper is a pure string utility — it performs no existence check or bundling of its own.

Use Icon (not Image) for all SVG icons that need to adapt to the current color theme. Image preserves the SVG’s original colors, while Icon masks the shape and fills it with the tint token — making it automatically adapt when the user switches between light and dark themes.

Get Started

Core Concepts

Layout Components

UI Components

Motion

Navigation

Examples

Image and Icon: Rendering Media and SVG Icon Assets

Image

Props

ContentScale values

Basic example

Using painterResource

Crop mode avatar

Icon

Props

How CSS masking works

Basic example

Using a ColorToken

Using a raw CSS color

Using MDI SVG icon URLs

painterResource helper

`painterResource(resourceName)`

`Res` namespace

Example using Res helper

Build docs developers (and LLMs) love

Get Started

Core Concepts

Layout Components

UI Components

Motion

Navigation

Examples

Documentation Index

​Image

​Props

​ContentScale values

​Basic example

​Using painterResource

​Crop mode avatar

​Icon

​Props

​How CSS masking works

​Basic example

​Using a ColorToken

​Using a raw CSS color

​Using MDI SVG icon URLs

​painterResource helper

​painterResource(resourceName)

​Res namespace

​Example using Res helper

Build docs developers (and LLMs) love

Image

Props

ContentScale values

Basic example

Using painterResource

Crop mode avatar

Icon

Props

How CSS masking works

Basic example

Using a ColorToken

Using a raw CSS color

Using MDI SVG icon URLs

painterResource helper

`painterResource(resourceName)`

`Res` namespace

Example using Res helper