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

Overlay container -- positions the second child as a floating overlay
relative to the first child (anchor).

## Props

- `position` (atom) -- overlay position relative to anchor: `:below`, `:above`,
  `:left`, `:right`. Default: `:below`.
- `gap` (number) -- space in pixels between anchor and overlay. Default: 0.
- `offset_x` (number) -- horizontal offset in pixels applied after positioning.
- `offset_y` (number) -- vertical offset in pixels applied after positioning.
- `width` (length) -- width of the overlay node. See `Toddy.Iced.Length`.
- `a11y` (map) -- accessibility overrides. See `Toddy.Iced.A11y`.

## Children

Exactly two children are expected:
1. The anchor widget (rendered inline in the layout).
2. The overlay content (rendered as a floating overlay above everything else).

# `option`

```elixir
@type option() ::
  {:position, position()}
  | {:gap, number()}
  | {:offset_x, number()}
  | {:offset_y, number()}
  | {:width, Toddy.Iced.Length.t()}
  | {:a11y, Toddy.Iced.A11y.t()}
```

# `position`

```elixir
@type position() :: :right | :left | :above | :below
```

# `t`

```elixir
@type t() :: %Toddy.Iced.Widget.Overlay{
  a11y: Toddy.Iced.A11y.t() | nil,
  children: [Toddy.Iced.ui_node() | struct()],
  gap: number() | nil,
  id: String.t(),
  offset_x: number() | nil,
  offset_y: number() | nil,
  position: position() | nil,
  width: Toddy.Iced.Length.t() | nil
}
```

# `a11y`

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

Sets accessibility annotations.

# `build`

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

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

# `extend`

```elixir
@spec extend(overlay :: t(), children :: [Toddy.Iced.ui_node() | struct()]) :: t()
```

Appends multiple children to the overlay.

# `gap`

```elixir
@spec gap(overlay :: t(), gap :: number()) :: t()
```

Sets the gap between anchor and overlay in pixels.

# `new`

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

Creates a new overlay struct with optional keyword opts.

# `offset_x`

```elixir
@spec offset_x(overlay :: t(), offset_x :: number()) :: t()
```

Sets the horizontal offset in pixels.

# `offset_y`

```elixir
@spec offset_y(overlay :: t(), offset_y :: number()) :: t()
```

Sets the vertical offset in pixels.

# `position`

```elixir
@spec position(overlay :: t(), position :: position()) :: t()
```

Sets the overlay position relative to the anchor.

# `push`

```elixir
@spec push(overlay :: t(), child :: Toddy.Iced.ui_node() | struct()) :: t()
```

Appends a child to the overlay.

# `width`

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

Sets the width of the overlay node.

# `with_options`

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

Applies keyword options to an existing overlay struct.

---

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