# `Tucan.Legend`
[🔗](https://github.com/pnezis/tucan/blob/v0.7.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_selectable`

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

Makes the legend of the given channel selectable.

Clicking on an entry of the legend highlights the data of this entry and fades the
rest. Shift-click selects multiple entries and a double click clears the selection.

It is applicable on single view and layered plots, with a legend on a field of the
given channel. In layered plots all layers with the same field are highlighted.

See also `Tucan.Interactive` for more interactive plots.

## Options

* `:unselected_opacity` (`t:number/0`) - The opacity of the data that are not selected. The default value is `0.15`.

## Examples

Click on a symbol of the legend to highlight its stock:

```tucan
Tucan.lineplot(:stocks, "date", "price", color_by: "symbol", x: [type: :temporal], width: 400)
|> Tucan.Legend.set_selectable(:color)
```

Legends of other channels can be selectable as well:

```tucan
Tucan.scatter(:penguins, "Beak Length (mm)", "Beak Depth (mm)", shape_by: "Island")
|> Tucan.Legend.set_selectable(:shape, unselected_opacity: 0.05)
```

# `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*