# `Tucan.Legend`
[🔗](https://github.com/pnezis/tucan/blob/v0.6.0/lib/tucan/legend.ex#L1)

Helper utilities for configuring the plot legend.

# `put_options`

```elixir
@spec put_options(vl :: VegaLite.t(), channel :: atom(), opts :: keyword()) ::
  VegaLite.t()
```

Set arbitrary options to the legend of the given channel.

The options are deep merged with existing options.

## Examples

```tucan
Tucan.scatter(:iris, "petal_width", "petal_length")
|> Tucan.color_by("species")
|> Tucan.Legend.put_options(:color, fill_color: "yellow", offset: 5, padding: 2, label_font_size: 14)
```

# `set_enabled`

```elixir
@spec set_enabled(vl :: VegaLite.t(), channel :: atom(), enabled :: boolean()) ::
  VegaLite.t()
```

Enables or disables the legend of the given encoding channel.

# `set_offset`

```elixir
@spec set_offset(vl :: VegaLite.t(), channel :: atom(), offset :: integer()) ::
  VegaLite.t()
```

Sets the offset in pixels by which to displace the legend from the data rectangle
and axes.

If not set defaults to 18 pixels.

## Examples

```tucan
Tucan.scatter(:iris, "petal_width", "petal_length")
|> Tucan.color_by("species")
|> Tucan.Legend.set_offset(:color, 5)
```

# `set_orientation`

```elixir
@spec set_orientation(
  vl :: VegaLite.t(),
  channel :: atom(),
  orientation :: String.t()
) :: VegaLite.t()
```

Sets the legend orientation with respect to the scene.

You need to define the `channel` for which the legend will be configured. Orientation
can be one of the following: `["left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right", "none"]`.

Applicable only on plots with a legend.

## Examples

```tucan
Tucan.scatter(:iris, "petal_width", "petal_length")
|> Tucan.color_by("species")
|> Tucan.shape_by("species")
|> Tucan.Legend.set_orientation(:color, "bottom")
|> Tucan.Legend.set_orientation(:shape, "top")
```

# `set_title`

```elixir
@spec set_title(
  vl :: VegaLite.t(),
  channel :: atom(),
  title :: String.t() | nil,
  opts :: keyword()
) :: VegaLite.t()
```

Sets the title of the given legend.

You can optionally pass any title option supported by vega-lite to customize the
style of it.

Applicable only on plots with a legend.

## Examples

```tucan
Tucan.scatter(:iris, "petal_width", "petal_length", color_by: "species")
|> Tucan.Legend.set_title(:color, "Iris Species", title_color: "red", title_font_weight: 300)
```

---

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