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

The select filter renders a select box for the implemented `options/1` and `prompt/0` callbacks. The `prompt/0` callback defines the key for the `nil` value added as first option.

See the following example for an implementation of an event status filter.

    defmodule MyAppWeb.Filters.EventStatusSelect do
      use Backpex.Filters.Select

      @impl Backpex.Filter
      def label, do: "Event status"

      @impl Backpex.Filters.Select
      def prompt, do: "Select an option..."

      @impl Backpex.Filters.Select
      def options(_assigns), do: [
        {"Open", :open},
        {"Close", :close},
      ]

      @impl Backpex.Filter
      def query(query, attribute, value) do
          where(query, [x], field(x, ^attribute) == ^value)
      end
    end

> #### `use Backpex.Filters.Select` {: .info}
>
> When you `use Backpex.Filters.Select`, the `Backpex.Filters.Select` 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 select filter.

# `prompt`

```elixir
@callback prompt() :: String.t() | atom()
```

The select's default option.

# `changeset`

Validates that the selected value exists in the options list.

Returns the changeset unchanged if the value is valid, or adds an error if not found in options.
Empty string is allowed as it represents the "no selection" state.

# `option_value_to_label`

Finds the label for a given option value.

Returns nil if the value is not found.

## Examples

    iex> options = [{"Open", :open}, {"Closed", :closed}]
    iex> Backpex.Filters.Select.option_value_to_label(options, "open")
    "Open"

    iex> options = [{"Open", :open}]
    iex> Backpex.Filters.Select.option_value_to_label(options, :open)
    "Open"

    iex> options = [{"Open", :open}]
    iex> Backpex.Filters.Select.option_value_to_label(options, "unknown")
    nil

    iex> options = [{"Active", "active"}, {"Inactive", "inactive"}]
    iex> Backpex.Filters.Select.option_value_to_label(options, "active")
    "Active"

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

    iex> Backpex.Filters.Select.option_value_to_label([], "value")
    nil

# `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 `[]`.

# `selected`

Converts empty string to nil, returns other values as-is.

## Examples

    iex> Backpex.Filters.Select.selected("")
    nil

    iex> Backpex.Filters.Select.selected("open")
    "open"

    iex> Backpex.Filters.Select.selected(:open)
    :open

    iex> Backpex.Filters.Select.selected(1)
    1

---

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