# Image

A responsive `<picture>`/`<img>` wrapper with lazy loading, placeholder, and load/error state styling.

## Usage

Use standalone.
```svelte
<Image src="/photo.jpg" alt="Photo" />
```

## Anatomy

The `class` attribute values represent part names, and `conditional` indicates elements that are rendered conditionally. Other attributes represent their corresponding props.

```svelte
<picture class="whole">
  <source srcset type media sizes width height conditional:sources />
  <img class="main" {...rest} {src} {alt} loading fetchpriority decoding style onload onerror data-loaded data-error />
</picture>
```

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `src*` | `string` | - | Image source for the inner `<img>` |
| `alt*` | `string` | - | Alternative text; empty string is valid for decorative images |
| `sources` | `ImageSource[]` | - | Alternate `<source>` candidates for the root `<picture>` |
| `placeholder` | `string` | - | CSS background shown on the image until it loads |
| `firstView` | `boolean` | `false` | Sets eager loading, high fetch priority, and default preload unless native attributes override it |
| `preload` | `boolean` | `firstView ?? false` | Adds a preload link for the highest-priority candidate |
| `onload` | `EventHandler` | - | Load handler on the inner `<img>` |
| `onerror` | `EventHandler` | - | Error handler on the inner `<img>` |
| `attach` | `Attachment` | - | Svelte attachment on the inner `<img>` |
| `element` | `HTMLImageElement` | - | Bindable inner image element |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Bindable variant |
`*` required. Other `HTMLImgAttributes` are passed to `<img>` via rest props; `class` is merged onto the root `<picture>`.

Supply both width and height when possible to reserve aspect ratio and minimize layout shift.

## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

The caller's variant is used in the neutral state until load. Successful load sets `data-loaded` and switches to `active`; load error sets `data-error` and switches to `inactive`. When `src` changes, the load state resets and the caller's variant is restored.

### Default Class Name

`svs-image`

## Behavior

`firstView` is sugar for eager loading, high fetch priority, and preload; native
`loading`, `fetchpriority`, and `decoding` attrs in `...rest` override the
defaults. Load sets `data-loaded` and `variant=ACTIVE`; error sets
`data-error` and `variant=INACTIVE`; neutral state restores the caller's
variant. A placeholder is emitted as the img background until load, then
cleared. Missing `<source>` types are derived from the first `srcset`
candidate's extension when known. Preload mirrors only the highest-priority
candidate (`sources[0]` or the img), so art-direction fan-out is intentionally
represented by a single preload link.

## Exports

### Types

```ts
interface ImageSource {
  srcset: string;
  type?: string;
  media?: string;
  sizes?: string;
  width?: number;
  height?: number;
}
interface ImageProps extends Omit<HTMLImgAttributes, "src" | "alt" | "onload" | "onerror"> {
  src: string;
  alt: string; // empty string is valid for decorative images
  sources?: ImageSource[]; // alternate <source> candidates
  placeholder?: string; // CSS background shown until load
  firstView?: boolean; // (false); sets eager/high/default preload unless overridden
  preload?: boolean; // (firstView ?? false)
  onload?: EventHandler<Event, HTMLImageElement> | null;
  onerror?: EventHandler<Event, HTMLImageElement> | null;
  attach?: Attachment<HTMLImageElement>;
  element?: HTMLImageElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // bindable (VARIANT.NEUTRAL)
  // other HTMLImgAttributes are passed to <img> via ...rest; `class` is merged onto root <picture>
}
type ImageReqdProps = "src" | "alt";
type ImageBindProps = "element" | "variant";
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=ImageBasic.svelte
<script lang="ts">
  import { Image } from "svseeds";

  const styling = {
    whole: "block w-72 overflow-hidden rounded-sm border border-gray-400",
    main: "aspect-video w-full object-cover transition-opacity data-[loaded]:opacity-100",
  };
  const myProps = {
    src: "/ogp.png",
    alt: "SvSeeds documentation preview",
    width: 1200,
    height: 630,
    placeholder: "linear-gradient(135deg, #d1d5db, #f8fafc)",
    styling,
  };
</script>

<Image {...myProps} />
```
### Load & Error States

**Code**

```svelte src=ImageVariant.svelte
<script lang="ts">
  import { Image } from "svseeds";

  const styling = {
    whole: {
      base: "block w-64 overflow-hidden rounded-sm border bg-white",
      neutral: "border-gray-400",
      active: "border-teal-500",
      inactive: "border-red-500",
    },
    main: {
      base: "aspect-video w-full object-cover",
      inactive: "opacity-35",
    },
  };
  const myProps1 = {
    src: "/ogp.png",
    alt: "Loaded SvSeeds preview",
    width: 1200,
    height: 630,
    placeholder: "linear-gradient(135deg, #ccfbf1, #f8fafc)",
    styling,
  };
  const myProps2 = {
    src: "data:image/png;base64,broken",
    alt: "Broken demo image",
    width: 1200,
    height: 630,
    placeholder: "linear-gradient(135deg, #fee2e2, #f8fafc)",
    styling,
  };
</script>

<div class="flex flex-col gap-4 sm:flex-row">
  <div class="space-y-2">
    <Image {...myProps1} />
    <p class="text-center text-sm">Loaded</p>
  </div>
  <div class="space-y-2">
    <Image {...myProps2} />
    <p class="text-center text-sm">Error</p>
  </div>
</div>
```