Phoenix implementation of Zag.js Select.

Anatomy

The placeholder text comes from the translation attribute (default English "Select" is passed through the host Phoenix gettext backend at render time when unchanged). Pass translation={%Select.Translation{placeholder: …}} to customize.

Minimal

<.select
  class="select"
  items={Corex.List.new([
    %{label: "France", value: "fra", disabled: true},
    %{label: "Belgium", value: "bel"},
    %{label: "Germany", value: "deu"},
    %{label: "Netherlands", value: "nld"},
    %{label: "Switzerland", value: "che"},
    %{label: "Austria", value: "aut"}
  ])}
>
  <:trigger>
    <.heroicon name="hero-chevron-down" />
  </:trigger>
</.select>

Grouped

<.select
  class="select"
  items={Corex.List.new([
    %{label: "France", value: "fra", group: "Europe"},
    %{label: "Belgium", value: "bel", group: "Europe"},
    %{label: "Germany", value: "deu", group: "Europe"},
    %{label: "Netherlands", value: "nld", group: "Europe"},
    %{label: "Switzerland", value: "che", group: "Europe"},
    %{label: "Austria", value: "aut", group: "Europe"},
    %{label: "Japan", value: "jpn", group: "Asia"},
    %{label: "China", value: "chn", group: "Asia"},
    %{label: "South Korea", value: "kor", group: "Asia"},
    %{label: "Thailand", value: "tha", group: "Asia"},
    %{label: "USA", value: "usa", group: "North America"},
    %{label: "Canada", value: "can", group: "North America"},
    %{label: "Mexico", value: "mex", group: "North America"}
  ])}
>
  <:trigger>
    <.heroicon name="hero-chevron-down" />
  </:trigger>
</.select>

Custom

This example requires the installation of Flagpack to display the use of custom item rendering.

<.select
  class="select"
  items={Corex.List.new([
    %{label: "France", value: "fra"},
    %{label: "Belgium", value: "bel"},
    %{label: "Germany", value: "deu"},
    %{label: "Netherlands", value: "nld"},
    %{label: "Switzerland", value: "che"},
    %{label: "Austria", value: "aut"}
  ])}
>
  <:label>
    Country of residence
  </:label>
  <:item :let={item}>
    <Flagpack.flag name={String.to_atom(to_string(item.value))} />
    {item.label}
  </:item>
  <:trigger>
    <.heroicon name="hero-chevron-down" />
  </:trigger>
  <:item_indicator>
    <.heroicon name="hero-check" />
  </:item_indicator>
</.select>

Custom Grouped

This example requires the installation of Flagpack to display the use of custom item rendering.

<.select
  class="select"
  items={Corex.List.new([
    %{label: "France", value: "fra", group: "Europe"},
    %{label: "Belgium", value: "bel", group: "Europe"},
    %{label: "Germany", value: "deu", group: "Europe"},
    %{label: "Japan", value: "jpn", group: "Asia"},
    %{label: "China", value: "chn", group: "Asia"},
    %{label: "South Korea", value: "kor", group: "Asia"}
  ])}
>
  <:item :let={item}>
    <Flagpack.flag name={String.to_atom(to_string(item.value))} />
    {item.label}
  </:item>
  <:trigger>
    <.heroicon name="hero-chevron-down" />
  </:trigger>
  <:item_indicator>
    <.heroicon name="hero-check" />
  </:item_indicator>
</.select>

Patterns

Navigation

Set redirect on the component so the first selected value is used as the destination URL. Per item, choose the navigation kind explicitly via the item's :redirect field:

• :href (default) - full page redirect via window.location (safe everywhere)
• :patch - LiveView js().patch(url) (caller asserts: same LV mount + matching live route)
• :navigate - LiveView js().navigate(url) (caller asserts: another LV in the same live_session)
• false - disable redirect for this item (e.g. let your on_value_change server handler decide)

Set new_tab: true on an item to open its destination in a new tab via window.open. An item may also set :to to override the destination (defaults to the item id).

Build items with Corex.List.new/1. When redirect is true, the client runs single-select in Zag even if multiple is set on the component.

Controller

When not connected to LiveView, the hook always performs a full page redirect via window.location.

<.select
  class="select"
  redirect
  translation={%Corex.Select.Translation{placeholder: "Go to"}}
  items={Corex.List.new([
    %{label: "Account", id: ~p"/account"},
    %{label: "Settings", id: ~p"/settings"}
  ])}
>
  <:trigger>
    <.heroicon name="hero-chevron-down" />
  </:trigger>
</.select>

LiveView

When connected to LiveView, use on_value_change and redirect in the callback. The payload includes value (list); use Enum.at(value, 0) for the destination.

defmodule MyAppWeb.NavLive do
  use MyAppWeb, :live_view

  def handle_event("nav_change", %{"value" => value}, socket) do
    path = Enum.at(value, 0) || ~p"/"
    {:noreply, push_navigate(socket, to: path)}
  end

  def render(assigns) do
    ~H"""
    <.select
      id="nav-select"
      class="select"
      redirect
      on_value_change="nav_change"
      translation={%Corex.Select.Translation{placeholder: "Go to"}}
      items={Corex.List.new([
        %{label: "Account", id: ~p"/account"},
        %{label: "Settings", id: ~p"/settings"}
      ])}
    >
      <:trigger>
        <.heroicon name="hero-chevron-down" />
      </:trigger>
    </.select>
    """
  end
end

Stream

Use Phoenix.LiveView.stream/3 to add or remove options at runtime. Keep @items_list in sync and pass Corex.List.new(@items_list) as items. Configure dom_id as select:stream-select:item:#{value}.

<.select class="select" items={Corex.List.new(@items_list)}>
  <:label>Country</:label>
  <:trigger>
    <.heroicon name="hero-chevron-down" class="icon" />
  </:trigger>
</.select>

Form

When using with Phoenix forms, set the form id in to_form/2 (for example to_form(changeset, as: :name, id: "my-form")) and use <.form for={@form}>.

For cross-cutting invalid styling and error presentation, see the Forms guide. Pass invalid={Corex.FormField.invalid?(@form[:field])} when you want alert borders after validation.

Multiple selection and {:array, :string} fields

With multiple and field={f[:tags]}, the hidden native <select> submits list params (post[tags][]), matching Phoenix's multi-select convention:

%{"post" => %{"tags" => ["option1", "option2"]}}

Pair with field :tags, {:array, :string} in your schema. Single-select forms still submit one scalar through the hidden value-input.

<.select
  field={@form[:tags]}
  class="select"
  multiple
  controlled
  items={Corex.List.new([
    %{label: "Option 1", value: "option1"},
    %{label: "Option 2", value: "option2"}
  ])}
  translation={%Corex.Select.Translation{placeholder: "Choose tags"}}
>
  <:label>Tags</:label>
  <:trigger><.heroicon name="hero-chevron-down" /></:trigger>
  <:error :let={msg}>
    <.heroicon name="hero-exclamation-circle" class="icon" />
    {msg}
  </:error>
</.select>

For free-form tags (not limited to items), use Corex.TagsInput with the same {:array, :string} field type.

Controller

Build the form from an Ecto changeset:

def form_page(conn, _params) do
  form =
    %MyApp.Form.SelectForm{}
    |> MyApp.Form.SelectForm.changeset(%{})
    |> Phoenix.Component.to_form(as: :select_form, id: "select-form")
  render(conn, :form_page, form: form)
end

<.form :let={f} for={@form} action={@action} method="post">
  <.select
    field={f[:country]}
    class="select"
    translation={%Corex.Select.Translation{placeholder: "Select a country"}}
    items={Corex.List.new([
      %{label: "France", value: "fra", disabled: true},
      %{label: "Belgium", value: "bel"},
      %{label: "Germany", value: "deu"},
      %{label: "Netherlands", value: "nld"},
      %{label: "Switzerland", value: "che"},
      %{label: "Austria", value: "aut"}
    ])}
  >
    <:label>Your country of residence</:label>
    <:trigger>
      <.heroicon name="hero-chevron-down" />
    </:trigger>
    <:error :let={msg}>
      <.heroicon name="hero-exclamation-circle" class="icon" />
      {msg}
    </:error>
  </.select>
  <button type="submit">Submit</button>
</.form>

Live View

When using in a Live view you must add controlled mode. Prefer building the form from an Ecto changeset (see "With Ecto changeset" below).

With Ecto changeset

When using Ecto changeset for validation and inside a Live view you must enable the controlled mode.

This allows the Live View to be the source of truth and the component to be in sync accordingly.

First create your schema and changeset:

defmodule MyApp.Accounts.User do
  use Ecto.Schema
  import Ecto.Changeset

  schema "users" do
    field :name, :string
    field :country, :string
    timestamps(type: :utc_datetime)
  end

  def changeset(user, attrs) do
    user
    |> cast(attrs, [:name, :country])
    |> validate_required([:name, :country])
  end
end

defmodule MyAppWeb.UserLive do
  use MyAppWeb, :live_view
  alias MyApp.Accounts.User

  def mount(_params, _session, socket) do
    {:ok, assign(socket, :form, to_form(User.changeset(%User{}, %{})))}
  end

  def handle_event("validate", %{"user" => user_params}, socket) do
    changeset = User.changeset(%User{}, user_params)
    {:noreply, assign(socket, form: to_form(changeset, action: :validate))}
  end

  def render(assigns) do
    ~H"""
    <.form for={@form} phx-change="validate">
      <.select
        field={@form[:country]}
        class="select"
        controlled
        translation={%Corex.Select.Translation{placeholder: "Select a country"}}
        items={Corex.List.new([
          %{label: "France", value: "fra"},
          %{label: "Belgium", value: "bel"},
          %{label: "Germany", value: "deu"}
        ])}
      >
        <:label>Your country of residence</:label>
        <:trigger>
          <.heroicon name="hero-chevron-down" />
        </:trigger>
        <:error :let={msg}>
          <.heroicon name="hero-exclamation-circle" class="icon" />
          {msg}
        </:error>
      </.select>
    </.form>
    """
  end
end

API

Requires a stable id on <.select>.

set_value

<.action phx-click={Corex.Select.set_value("select-api-bind", ["fra"])} class="button button--sm">France</.action>
<.select id="select-api-bind" class="select" items={
  Corex.List.new([
    %{label: "France", value: "fra"},
    %{label: "Belgium", value: "bel"},
    %{label: "Germany", value: "deu"}
  ])
}>
  <:trigger><.heroicon name="hero-chevron-down" /></:trigger>
</.select>

def handle_event("select_api_set_value", _, socket) do
  {:noreply, Corex.Select.set_value(socket, "select-api-srv", ["fra"])}
end

Events

Server events

on_value_change

<.select
  class="select"
  items={Corex.List.new([
    %{label: "France", value: "fra"},
    %{label: "Belgium", value: "bel"},
    %{label: "Germany", value: "deu"}
  ])}
  on_value_change="select_value_changed"
>
  <:trigger><.heroicon name="hero-chevron-down" /></:trigger>
</.select>

def handle_event("select_value_changed", %{"value" => value}, socket) do
  {:noreply, assign(socket, :selected, value)}
end

Client events

on_value_change_client

<.select
  id="select-events-client"
  class="select"
  items={Corex.List.new([
    %{label: "France", value: "fra"},
    %{label: "Belgium", value: "bel"},
    %{label: "Germany", value: "deu"}
  ])}
  on_value_change_client="select-value-changed"
>
  <:trigger><.heroicon name="hero-chevron-down" /></:trigger>
</.select>

document.getElementById("select-events-client")?.addEventListener("select-value-changed", (e) => {
  console.log(e.detail);
});

Style

Target parts with data-scope and data-part:

[data-scope="select"][data-part="root"] {}
[data-scope="select"][data-part="control"] {}
[data-scope="select"][data-part="label"] {}
[data-scope="select"][data-part="input"] {}
[data-scope="select"][data-part="error"] {}
[data-scope="select"][data-part="trigger"] {}
[data-scope="select"][data-part="item-group"] {}
[data-scope="select"][data-part="item-group-label"] {}
[data-scope="select"][data-part="item"] {}
[data-scope="select"][data-part="item-text"] {}
[data-scope="select"][data-part="item-indicator"] {}

@import "../corex/main.css";
@import "../corex/tokens/themes/neo/light.css";
@import "../corex/components/select.css";

Stack modifiers on <.select class="select ...">.

Color

Color modifiers apply theme ink to the trigger label and chevron, and to selected menu items.

Size

Text

Rounded

Max width