# `Toddy.Iced.Widget.Image`
[🔗](https://github.com/toddy-ui/toddy-elixir/blob/v0.3.0/lib/toddy/iced/widget/image.ex#L1)

Image display -- renders a raster image from a file path or an in-memory handle.

## Props

- `source` (string or handle ref) -- path to the image file, or
  `%{handle: name}` for an in-memory image created via `Toddy.Command.create_image/2`.
- `width` (length) -- image width. Default: shrink. See `Toddy.Iced.Length`.
- `height` (length) -- image height. Default: shrink.
- `content_fit` -- how the image fits its bounds. See `Toddy.Iced.ContentFit`.
- `rotation` (number) -- rotation angle in degrees.
- `opacity` (number) -- opacity from 0.0 (transparent) to 1.0 (opaque).
- `border_radius` (number) -- corner radius in pixels.
- `filter_method` -- image interpolation mode. See `Toddy.Iced.FilterMethod`.
- `expand` (boolean) -- expand image to fill available space.
- `scale` (number) -- scale factor for the image.
- `crop` (map) -- crop rectangle: `%{x, y, width, height}` (integer pixel values).
- `alt` (string) -- alt text for the image (accessibility).
- `description` (string) -- longer description for the image (accessibility).
- `a11y` (map) -- accessibility overrides. See `Toddy.Iced.A11y`.

# `option`

```elixir
@type option() ::
  {:width, Toddy.Iced.Length.t()}
  | {:height, Toddy.Iced.Length.t()}
  | {:content_fit, Toddy.Iced.ContentFit.t()}
  | {:rotation, number()}
  | {:opacity, number()}
  | {:border_radius, number()}
  | {:filter_method, Toddy.Iced.FilterMethod.t()}
  | {:expand, boolean()}
  | {:scale, number()}
  | {:crop, map()}
  | {:alt, String.t()}
  | {:description, String.t()}
  | {:a11y, Toddy.Iced.A11y.t()}
```

# `source`

```elixir
@type source() :: String.t() | %{handle: String.t()}
```

Image source: a file path string or a handle reference map.

# `t`

```elixir
@type t() :: %Toddy.Iced.Widget.Image{
  a11y: Toddy.Iced.A11y.t() | nil,
  alt: String.t() | nil,
  border_radius: number() | nil,
  content_fit: Toddy.Iced.ContentFit.t() | nil,
  crop: map() | nil,
  description: String.t() | nil,
  expand: boolean() | nil,
  filter_method: Toddy.Iced.FilterMethod.t() | nil,
  height: Toddy.Iced.Length.t() | nil,
  id: String.t(),
  opacity: number() | nil,
  rotation: number() | nil,
  scale: number() | nil,
  source: source(),
  width: Toddy.Iced.Length.t() | nil
}
```

# `a11y`

```elixir
@spec a11y(image :: t(), a11y :: Toddy.Iced.A11y.t()) :: t()
```

Sets accessibility annotations.

# `alt`

```elixir
@spec alt(image :: t(), alt :: String.t()) :: t()
```

Sets the alt text for the image.

# `border_radius`

```elixir
@spec border_radius(image :: t(), border_radius :: number()) :: t()
```

Sets the border radius in pixels.

# `build`

```elixir
@spec build(image :: t()) :: Toddy.Iced.ui_node()
```

Converts this image struct to a `ui_node()` map via the `Toddy.Iced.Widget` protocol.

# `content_fit`

```elixir
@spec content_fit(image :: t(), content_fit :: Toddy.Iced.ContentFit.t()) :: t()
```

Sets how the image fits its bounds.

# `crop`

```elixir
@spec crop(image :: t(), crop :: map()) :: t()
```

Sets the crop rectangle.

# `description`

```elixir
@spec description(image :: t(), description :: String.t()) :: t()
```

Sets a longer description for the image.

# `expand`

```elixir
@spec expand(image :: t(), expand :: boolean()) :: t()
```

Sets whether the image expands to fill available space.

# `filter_method`

```elixir
@spec filter_method(image :: t(), filter_method :: Toddy.Iced.FilterMethod.t()) :: t()
```

Sets the image filter method.

# `height`

```elixir
@spec height(image :: t(), height :: Toddy.Iced.Length.t()) :: t()
```

Sets the image height.

# `new`

```elixir
@spec new(id :: String.t(), source :: source(), opts :: [option()]) :: t()
```

Creates a new image struct with the given source and optional keyword opts.

The `source` can be a file path string or a handle reference map
(`%{handle: "name"}`) for in-memory images created via
`Toddy.Command.create_image/2`.

# `opacity`

```elixir
@spec opacity(image :: t(), opacity :: number()) :: t()
```

Sets the image opacity (0.0 to 1.0).

# `rotation`

```elixir
@spec rotation(image :: t(), rotation :: number()) :: t()
```

Sets the rotation angle in degrees.

# `scale`

```elixir
@spec scale(image :: t(), scale :: number()) :: t()
```

Sets the image scale factor.

# `width`

```elixir
@spec width(image :: t(), width :: Toddy.Iced.Length.t()) :: t()
```

Sets the image width.

# `with_options`

```elixir
@spec with_options(image :: t(), opts :: [option()]) :: t()
```

Applies keyword options to an existing image struct.

---

*Consult [api-reference.md](api-reference.md) for complete listing*