# `Backpex.Filters.MultiSelect`
[🔗](https://github.com/naymspace/backpex/blob/0.18.3/lib/backpex/filters/multi_select.ex#L1)

The multi select filter renders checkboxes for a given list of options, hence allowing the user to select multiple values.

See the following example for an implementation of a multi select user filter.

    defmodule MyAppWeb.Filters.MultiUserSelect do
      use Backpex.Filters.MultiSelect

      @impl Backpex.Filter
      def label, do: "User"

      @impl Backpex.Filters.MultiSelect
      def prompt, do: "Select user ..."

      @impl Backpex.Filters.MultiSelect
      def options, do: [
        {"John Doe", "acdd1860-65ce-4ed6-a37c-433851cf68d7"},
        {"Jane Doe", "9d78ce5e-9334-4a6c-a076-f1e72522de2"}
      ]
    end

> #### `use Backpex.Filters.MultiSelect` {: .info}
>
> When you `use Backpex.Filters.MultiSelect`, the `Backpex.Filters.MultiSelect` module will set `@behavior Backpex.Filters.Select`. In addition it will add a `render` and `render_form` function in order to display the corresponding filter.

# `options`

```elixir
@callback options(assigns :: map()) :: [{String.t() | atom(), String.t() | atom()}]
```

The list of options for the multi select filter.

# `changeset`

Validates that all selected values exist in the options list.

Returns the changeset unchanged if all values are valid, or adds an error if any value is not found in options.

# `find_option_label`

Finds the label for a given option key.

Returns empty string if the key is not found.

## Examples

    iex> options = [{"John Doe", "uuid-1"}, {"Jane Doe", "uuid-2"}]
    iex> Backpex.Filters.MultiSelect.find_option_label(options, "uuid-1")
    "John Doe"

    iex> options = [{"John Doe", "uuid-1"}]
    iex> Backpex.Filters.MultiSelect.find_option_label(options, "unknown")
    ""

    iex> options = [{"Active", :active}, {"Inactive", :inactive}]
    iex> Backpex.Filters.MultiSelect.find_option_label(options, :active)
    "Active"

    iex> options = [{"Active", :active}]
    iex> Backpex.Filters.MultiSelect.find_option_label(options, "active")
    "Active"

    iex> Backpex.Filters.MultiSelect.find_option_label([{"Test", "value"}], nil)
    ""

# `option_value_to_label`

Converts a list of option values to their corresponding labels.

Returns a list with labels interspersed with commas for display.

## Examples

    iex> options = [{"John Doe", "uuid-1"}, {"Jane Doe", "uuid-2"}]
    iex> Backpex.Filters.MultiSelect.option_value_to_label(options, ["uuid-1", "uuid-2"])
    ["John Doe", ", ", "Jane Doe"]

    iex> options = [{"John Doe", "uuid-1"}]
    iex> Backpex.Filters.MultiSelect.option_value_to_label(options, ["uuid-1"])
    ["John Doe"]

    iex> options = [{"John Doe", "uuid-1"}]
    iex> Backpex.Filters.MultiSelect.option_value_to_label(options, [])
    []

    iex> options = [{"John Doe", "uuid-1"}]
    iex> Backpex.Filters.MultiSelect.option_value_to_label(options, ["unknown-uuid"])
    [""]

    iex> options = [{"John Doe", "uuid-1"}, {"Jane Doe", "uuid-2"}, {"Bob Smith", "uuid-3"}]
    iex> Backpex.Filters.MultiSelect.option_value_to_label(options, ["uuid-1", "uuid-2", "uuid-3"])
    ["John Doe", ", ", "Jane Doe", ", ", "Bob Smith"]

# `query`

# `render`

## Attributes

* `value` (`:any`) (required)
* `options` (`:list`) (required)

# `render_form`

## Attributes

* `form` (`:any`) (required)
* `field` (`:atom`) (required)
* `value` (`:any`) (required)
* `options` (`:list`) (required)
* `prompt` (`:string`) (required)
* `errors` (`:list`) - Defaults to `[]`.

---

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