# Image

> Displays files, URLs, encoded bytes or raw RGBA pixels.

Displays a raster image (PNG, JPEG, WebP, ICO), an SVG, an HTTP(S) URL or in-memory bytes.

On Windows, `src` may also name an executable, library or shortcut (`.exe`, `.dll`, `.lnk`):
the image is the file's shell icon as Explorer draws it (a shortcut shows its target's icon),
256 px when the file carries a jumbo icon, else 48 or 32 px. Other platforms decode those paths
as ordinary images, so they fail and fire `onError` (or show `fallbackSrc`).

- Category: [Text & media](https://tarve.dev/docs.md#text-media)
- Import: `import { Image } from "@tarve/core";`
- Props type: `ImageProps`
- Source: [packages/core/src/components/image.ts:305](https://github.com/omarcosr/tarve/blob/main/packages/core/src/components/image.ts#L305)

## Usage

```tsx title="Image.tsx"
import { Image } from "@tarve/core";

<Image src="assets/photo.png" width={320} height={200} fit="cover" style={{ radius: 12 }} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` (required) | `ImageSource` | — | Local path, `http(s)://` URL, data URL, encoded bytes, or raw RGBA8 pixels. A URL is fetched and decoded natively, off the UI thread, the first time the image is on screen (like `loading="lazy"`); until then it shows its placeholder. |
| `fallbackSrc` | `ImageSource` | — | Shown instead of a string `src` once it fails (an `onerror` swap to a placeholder), until `clearImageSourceCache()`. |
| `fit` | `"cover" \| "contain" \| "fill"` | — | CSS `object-fit`. |
| `height` | `number` | — |  |
| `onError` | `(event: ImageErrorEvent) => void` | — | The source failed to load or decode (HTML `onerror`): a missing file, a bad image, an HTTP error. |
| `width` | `number` | — |  |

## Common props

Shared by every component (descriptions: https://tarve.dev/docs.md#common-props): `children`, `class`, `className`, `highlight`, `id`, `key`, `motionFrom`, `onHighlight`, `onPaste`, `onPointerLeave`, `onPointerMove`, `onSize`, `onTransitionEnd`, `rovingGroup`, `style`.

## Types

```ts title="ImageErrorEvent"
interface ImageErrorEvent {
  /** The source that failed (a path or URL; empty for bytes and pixels). */
  src: string;
  message: string;
}
```

```ts title="ImageSource"
type ImageSource = string | Uint8Array | ImageBytesSource | ImageRgbaSource;
```

Previous: [Kbd](https://tarve.dev/docs/components/Kbd.md) · Next: [Avatar](https://tarve.dev/docs/components/Avatar.md)

---

Tarve v0.13.8 · HTML version: https://tarve.dev/docs/components/Image · Index for agents: https://tarve.dev/llms.txt
