---
url: https://native-shell.com/modules/nsh-image
description: "Image: the image element, plus Image.getSize and Image.prefetch for image information and loading ahead."
---

# nsh/image

`nsh/image` exports `Image`, the [`<Image>`](https://native-shell.com/elements/image.md) element that shows images. The same `Image` also asks the native image loader about images without showing them: their size, and loading them before they are shown.

```ts
import { Image, type ImageSize } from "nsh/image";
```

`Image` is a component carrying two functions: `<Image src=…>` renders the native image view (the compiler makes it in place, as it does `<View>`), and `Image.getSize` / `Image.prefetch` are called on it directly.

```ts
const Image: ((props: ImageProps) => YNode) & {
  getSize(source: string | { uri: string }): Promise<ImageSize>;
  prefetch(source: string | { uri: string }): Promise<boolean>;
};
```

See [Images and assets](https://native-shell.com/docs/images-and-assets.md) for the guide.

## Image.getSize

```ts
getSize(source: string | { uri: string }): Promise<ImageSize>;

interface ImageSize {
  width: number;   // pixels
  height: number;
}
```

Loads the image and resolves with its size in pixels (of the source image, not a downsampled copy). The loaded bytes stay in memory, so the `<Image>` that shows it next does not download it again. The promise rejects if the image cannot be loaded.

```tsx
import { signal } from "nsh";
import { Image } from "nsh/image";

const url = "https://picsum.photos/seed/nsh/1200/800";
const ratio = signal(1);

Image.getSize(url).then(({ width, height }) => ratio.set(width / height));

<Image src={url} style={{ width: "100%", aspectRatio: ratio() }} />;
```

## Image.prefetch

```ts
prefetch(source: string | { uri: string }): Promise<boolean>;
```

Loads an image ahead of showing it. Resolves with `true` once its bytes are in memory (`false` when it could not be loaded). Use it for the next page of a gallery or the image behind a tap.

```ts
const next = photos.slice(index + 1, index + 4);
next.forEach((p) => Image.prefetch(p.url));
```

## Related

- [`<Image>`](https://native-shell.com/elements/image.md): `src`, `resizeMode`, `defaultSource`, `onLoad`, `onProgress`, `onError` and the other props.
- Importing an image file (`import logo from "./logo.png"`) gives an `ImageAsset` (`{ uri, width, height }`, sized in points) that `<Image src>` and canvas `drawImage` accept.

> [!NOTE]
> When your app declares `capabilities` in `nsh.json`, `getSize` and `prefetch` of remote URLs must be allowed under `network`, like `fetch`. See [Sandbox and capabilities](https://native-shell.com/docs/sandbox-and-capabilities.md).