# Image

A picture in content, such as a screenshot or an illustration in documentation. It scales down to fit its container, keeps its aspect ratio, and centers when it's narrower.

```tsx
// demo.tsx
import {Image} from '@earendil-works/elanor-react';

// A 1600 × 800 illustration, wider than the demo, so it scales down.
const illustration = `data:image/svg+xml,${encodeURIComponent(
  '<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="800" viewBox="0 0 1600 800">' +
    '<rect width="1600" height="800" fill="#dfe7ec"/>' +
    '<circle cx="1220" cy="230" r="110" fill="#f4c96b"/>' +
    '<path d="M0 620 L420 300 L760 560 L1080 360 L1600 700 V800 H0 Z" fill="#7f9aa8"/>' +
    '<path d="M0 700 L520 480 L940 690 L1300 560 L1600 640 V800 H0 Z" fill="#4f6a78"/>' +
    '</svg>',
)}`;

export default function ImageDemo() {
  return <Image src={illustration} width={1600} height={800} alt="Mountains under a yellow sun" />;
}
```

## Usage

```tsx
import {Image} from '@earendil-works/elanor-react';

<Image
  src="/screenshots/settings.png"
  width={1600}
  height={800}
  alt="The workspace settings page"
/>;
```

Image renders an `img` with `semantic.dimension.radius.default` corners. `alt` is required: describe what the image shows, or pass `""` when it's decorative. Set `width` and `height` to the image's own size, so the page reserves its space before it loads. It decodes off the main thread (`decoding="async"`) unless you pass `decoding`.

## Narrower than its container

An image never grows past its own width; a narrow one centers.

```tsx
// small.tsx
import {Image} from '@earendil-works/elanor-react';

// A 320 × 200 illustration, narrower than the demo, so it stays at its size and centers.
const illustration = `data:image/svg+xml,${encodeURIComponent(
  '<svg xmlns="http://www.w3.org/2000/svg" width="320" height="200" viewBox="0 0 320 200">' +
    '<rect width="320" height="200" fill="#dfe7ec"/>' +
    '<circle cx="230" cy="64" r="28" fill="#f4c96b"/>' +
    '<path d="M0 160 L90 90 L160 150 L220 110 L320 170 V200 H0 Z" fill="#4f6a78"/>' +
    '</svg>',
)}`;

export default function ImageSmall() {
  return <Image src={illustration} width={320} height={200} alt="Mountains under a yellow sun" />;
}
```

## API

### `Image`

A centered image that scales down to fit its container and keeps its aspect ratio. It decodes off the main thread unless `decoding` says otherwise.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alt` (required) | `string` | - | Describe the image, or pass an empty string when it is decorative. |
| `decoding` | `'async' \| 'auto' \| 'sync'` | `'async'` |  |

Renders `<img>`. Also accepts its HTML attributes and `ref`.