# Image

An image with a placeholder while it loads and a fallback when it fails.

Source: [image.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/image.tsx)

```tsx
import { Image } from "@/components/ui/image";
import { gradientImage } from "@/examples/data";

export default function ImageBasic() {
  return (
    <Image
      src={gradientImage("#a2bcff", "#3b5cf6", 480, 320)}
      alt="A gradient from light to dark blue"
      width={480}
      height={320}
      className="h-auto w-full max-w-sm rounded-lg"
    />
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/image
```

## Usage

```tsx
import { Image } from "@/components/ui/image";

export function TeamPhoto() {
  return (
    <Image
      src="/photos/team.jpg"
      alt="The team at the offsite"
      width={480}
      height={320}
      className="h-auto w-full rounded-lg"
    />
  );
}
```

Image renders an `<img>`. It fills its box with the `layer-1` color until the image loads, and draws
a faint edge so a light image stands out from a light page. Pass `outline-0` to remove the edge,
such as for a logo with a transparent background.

`alt` is required. Describe what the image shows, or pass an empty string for an image that's only
decoration, so screen readers skip it. Images load lazily, so the browser fetches them only as they
near the viewport. Pass `loading="eager"` for an image at the top of the page.

Pass `draggable={false}` so someone can't drag the image out of the page. A
[Carousel](https://ui.jarv.is/components/carousel.md) already keeps a mouse drag from picking up its images.

The image sets `data-loading` while it loads and `data-loaded` once it has, for your own styles.

## Examples

### Sizing

Give an image `width` and `height`, or an aspect ratio class such as `aspect-video`, so the page
reserves its space before it loads. Add `object-cover` to crop an image to that shape rather than
stretch it.

```tsx
import { Image } from "@/components/ui/image";
import { gradientImage } from "@/examples/data";

export default function ImageSizing() {
  return (
    <div className="grid w-full max-w-md grid-cols-3 items-start gap-3">
      <Image
        src={gradientImage("#f2cf76", "#f17471", 320, 320)}
        alt="A gradient from yellow to red"
        className="aspect-square w-full rounded-md object-cover"
      />
      <Image
        src={gradientImage("#b8e9c1", "#198b43", 320, 320)}
        alt="A gradient from pale to deep green"
        className="aspect-[3/4] w-full rounded-md object-cover"
      />
      <Image
        src={gradientImage("#f2bbb7", "#b82d35", 320, 320)}
        alt="A gradient from pink to crimson"
        className="aspect-video w-full rounded-md object-cover"
      />
    </div>
  );
}
```

### Fallback

An image that fails to load becomes an icon in the same box, with `data-error`. Pass `fallback` to
show something else. Screen readers still announce the `alt` text.

```tsx
import { Image } from "@/components/ui/image";

export default function ImageFallback() {
  return (
    <div className="flex flex-wrap items-start gap-3">
      <Image
        src="/photos/missing.jpg"
        alt="The team at the offsite"
        width={160}
        height={120}
        className="rounded-md"
      />
      <Image
        src="/photos/missing.jpg"
        alt="The team at the offsite"
        width={160}
        height={120}
        className="rounded-md"
        fallback={<span className="text-xs text-muted-foreground">No preview</span>}
      />
    </div>
  );
}
```

### Loading state

An `<img>` can't hold other elements, so place a [Skeleton](https://ui.jarv.is/components/skeleton.md) or
[Spinner](https://ui.jarv.is/components/spinner.md) beside the image to show while it loads. Mark the image as a `peer`,
and give the overlay `hidden` and `peer-data-loading:block`.

```tsx
import { Image } from "@/components/ui/image";
import { Skeleton } from "@/components/ui/skeleton";

export function TeamPhoto() {
  return (
    <div className="relative w-full max-w-sm">
      <Image
        src="/photos/team.jpg"
        alt="The team at the offsite"
        width={480}
        height={320}
        className="peer h-auto w-full rounded-lg"
      />
      <Skeleton className="absolute inset-0 hidden rounded-lg peer-data-loading:block" />
    </div>
  );
}
```

Image sets `data-loading` only after it hydrates, and only on an image that's still loading. So the
overlay never covers an image that loaded before the page became interactive. It also disappears
when the image fails, so the fallback shows. To show a Spinner instead, center it with
`absolute inset-0 m-auto`.

## Frameworks

To optimize images with your framework, pass its image component to `render`. Image merges its
class names, attributes and load handlers into the framework's `<img>`. It leaves `loading` and
`decoding` to the framework's component.

**Next.js**

Wrap Image once with `next/image`, which takes the image's `src`, sizes and loading options.

```tsx title="components/app-image.tsx"
import NextImage, { type ImageProps as NextImageProps } from "next/image";

import { Image } from "@/components/ui/image";

export function AppImage({ alt, className, ...props }: NextImageProps) {
  return <Image alt={alt} className={className} render={<NextImage alt={alt} {...props} />} />;
}
```

A `fill` image positions itself in its parent, so place it in an
[Aspect Ratio](https://ui.jarv.is/components/aspect-ratio.md).

**Vite**

[Unpic](https://unpic.pics) resizes images through your image CDN. Wrap Image once with its
`Image`.

```tsx title="src/components/app-image.tsx"
import { Image as UnpicImage, type ImageProps as UnpicImageProps } from "@unpic/react";

import { Image } from "@/components/ui/image";

export function AppImage({ alt, className, ...props }: UnpicImageProps & { alt: string }) {
  return <Image alt={alt} className={className} render={<UnpicImage alt={alt} {...props} />} />;
}
```

**TanStack Start**

[Unpic](https://unpic.pics) resizes images through your image CDN. Wrap Image once with its
`Image`.

```tsx title="src/components/app-image.tsx"
import { Image as UnpicImage, type ImageProps as UnpicImageProps } from "@unpic/react";

import { Image } from "@/components/ui/image";

export function AppImage({ alt, className, ...props }: UnpicImageProps & { alt: string }) {
  return <Image alt={alt} className={className} render={<UnpicImage alt={alt} {...props} />} />;
}
```

## Props

| Part | Extends |
| --- | --- |
| `Image` | `<img>` |

Base UI's [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides say more about `className`, `style` and `render`.

### Image

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alt`        | `string`                                                 | —       | Describes the image to screen readers. Pass an empty string for an image that's only decoration.                                                                                          |
| `fallback?`  | `React.ReactNode`                                        | —       | Replaces the image when it fails to load. Defaults to an icon.                                                                                                                            |
| `draggable?` | `boolean`                                                | `true`  | Whether someone can drag the image out of the page, as a file or a link. Images are draggable unless you pass `false`.                                                                    |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
