Image

Since v0.5.0@kobalte/core/imageSource

An image element with an optional fallback for loading and error status.

Import

import { Image } from "@kobalte/core/image";
// or
import { Root, Img, ... } from "@kobalte/core/image";
// or (deprecated)
import { Image } from "@kobalte/core";

Features

Automatic and manual control over when the image renders.
Fallback part accepts any children.
Optionally delay fallback rendering to avoid content flashing.

Anatomy

The image consists of:

Image: The root container for an image.
Image.Img: The image to render. By default, it will only render when it has loaded.
Image.Fallback: An element that renders when the image hasn't loaded. This means whilst it's loading, or if there was an error.

<Image>
  <Image.Img />
  <Image.Fallback />
</Image>

Example

import { Image } from "@kobalte/core/image";

export function BasicExample() {
  return (
    <div class="flex items-center space-x-2">
      <Image fallbackDelay={600} class={style.image}>
        <Image.Img
          class={style.image__img}
          src="https://randomuser.me/api/portraits/women/44.jpg"
          alt="Nicole Steeves"
        />
        <Image.Fallback class={style.image__fallback}>NS</Image.Fallback>
      </Image>
      <Image class={style.image}>
        <Image.Fallback class={style.image__fallback}>MD</Image.Fallback>
      </Image>
    </div>
  );
}

.image {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  vertical-align: middle;
  overflow: hidden;
  user-select: none;
  width: 56px;
  height: 56px;
  border-radius: 100%;
  background-color: hsl(240 6% 90%);
}

.image__img {
  width: 100%;
  height: 100%;
  object-fit: cover;
  border-radius: inherit;
}

.image__fallback {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  background-color: hsl(204 94% 94%);
  color: hsl(201 96% 32%);
  font-size: 16px;
  line-height: 1;
  font-weight: 500;
}

[data-theme*="dark"] .image__fallback {
  background-color: hsl(202 80% 24%);
  color: hsl(198 93% 60%);
}

Usage

Avoid flash during loading

By default Image.Fallback will render when the image hasn't loaded. This means whilst it's loading, or if there was an error.

If you notice a flash during loading, use the fallbackDelay prop to delay its rendering, so it only renders for those with slower internet connections.

<Image fallbackDelay={600} class="image">
  <Image.Img
    class="image__img"
    src="https://randomuser.me/api/portraits/women/44.jpg"
    alt="Nicole Steeves"
  />
  <Image.Fallback class="image__fallback">NS</Image.Fallback>
</Image>

API Reference

Image

Image is equivalent to the Root import from @kobalte/core/image (and deprecated Image.Root).

Prop	Description
fallbackDelay	`number` The delay (in ms) before displaying the image fallback. Useful if you notice a flash during loading for delaying rendering, so it only appears for those with slower internet connections.
onLoadingStatusChange	`(status: "idle" \| "loading" \| "loaded" \| "error") => void` A callback providing information about the loading status of the image. This is useful in case you want to control more precisely what to render as the image is loading.

Rendered elements

Component	Default rendered element
`Image`	`span`
`Image.Img`	`img`
`Image.Fallback`	`span`

Last updated: 7/16/26, 7:09 AM

Edit this page on GitHub