Corex.Select (Corex v0.1.0-beta.5)

View Source

Phoenix implementation of Zag.js Select.

Examples

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
  id="my-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>

Use as 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
  id="nav-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

Phoenix Form Integration

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 id={@form.id} on <.form>.

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} id={@form.id} 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} id={@form.id} 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 Control

<.action phx-click={Corex.Select.set_value("my-select", ["fra"])} class="button button--sm">France</.action>
<.action phx-click={Corex.Select.set_open("my-select", true)} class="button button--sm">Open</.action>
def handle_event("api", _, socket) do
  {:noreply, Corex.Select.set_value(socket, "my-select", ["bel"])}
end

Styling

Use data attributes to target elements:

[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"] {}

If you wish to use the default Corex styling, you can use the class select on the component. This requires to install Mix.Tasks.Corex.Design first and import the component css file.

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

You can then use modifiers

<.select class="select select--accent select--lg">

Summary

API

set_open(select_id, open)

Opens or closes the menu. Dispatches corex:select:set-open on the hook root.

set_open(socket, select_id, open)

Sets open state from the server via push_event (select_set_open).

set_value(select_id, value)

Sets select value in the client. Dispatches corex:select:set-value on the hook root.

set_value(socket, select_id, value)

Sets select value from the server via push_event (select_set_value).

Functions

select(assigns)

API

set_open(select_id, open)

Opens or closes the menu. Dispatches corex:select:set-open on the hook root.

set_open(socket, select_id, open)

Sets open state from the server via push_event (select_set_open).

set_value(select_id, value)

Sets select value in the client. Dispatches corex:select:set-value on the hook root.

set_value(socket, select_id, value)

Sets select value from the server via push_event (select_set_value).

Functions

select(assigns)

Attributes

  • id (:string) - The id of the select component.

  • items (:list) - List of items from Corex.List.new/1 (or maps with :label and optional :value). Defaults to [].

  • controlled (:boolean) - Whether the select is controlled. Defaults to false.

  • value (:list) - The value of the select. Defaults to [].

  • disabled (:boolean) - Whether the select is disabled. Defaults to false.

  • close_on_select (:boolean) - Whether to close the select on select. Defaults to true.

  • dir (:string) - The direction of the select (ltr or rtl). Defaults to nil. Must be one of nil, "ltr", or "rtl".

  • orientation (:string) - Layout orientation for CSS (vertical or horizontal). Defaults to "vertical". Must be one of "vertical", or "horizontal".

  • loop_focus (:boolean) - Whether to loop focus the select. Defaults to false.

  • multiple (:boolean) - Whether to allow multiple selection. Defaults to false.

  • invalid (:boolean) - Whether the select is invalid. Defaults to false.

  • name (:string) - The name of the select.

  • form (:string) - The id of the form of the select.

  • read_only (:boolean) - Whether the select is read only. Defaults to false.

  • required (:boolean) - Whether the select is required. Defaults to false.

  • deselectable (:boolean) - Whether the selected items can be deselected. Defaults to false.

  • update_trigger (:boolean) - When false, the hook does not overwrite trigger item-text from the selected label. Defaults to true.

  • on_value_change (:string) - Server event name to push on value change. Payload includes value (list), path (current path without locale), id, items. Use Enum.at(value, 0) for the first selected value. Defaults to nil.

  • on_value_change_client (:any) - Client-side only: either a string (CustomEvent name to dispatch) or a Phoenix.LiveView.JS command. For JS commands, placeholders are replaced at run time: __VALUE__ (selected value(s) as JSON array), __VALUE_0__ (first value). For redirect-on-select use redirect instead (no placeholders).

    Defaults to nil.

  • redirect (:boolean) - When true, selecting a value triggers redirect-on-select. Each item picks the navigation kind via :redirect (:href (default) | :patch | :navigate | false). Items may also set :to (overrides the destination) and :new_tab (opens in a new tab). When true, the client runs single-select in Zag even if multiple is set on this component.

    Defaults to false.

  • positioning (Corex.Positioning) - Positioning options for the dropdown. Defaults to %Corex.Positioning{hide_when_detached: true, strategy: "fixed", placement: "bottom", gutter: 8, shift: 0, overflow_padding: 0, arrow_padding: 4, flip: true, slide: true, overlap: false, same_width: true, fit_viewport: true, offset: nil}.

  • translation (Corex.Select.Translation) - Translatable strings for the select. Defaults to %Corex.Select.Translation{placeholder: "Select"}.

  • field (Phoenix.HTML.FormField) - A form field struct retrieved from the form, for example: @form[:country]. Automatically sets id, name, value, and errors from the form field.

  • errors (:list) - List of error messages to display. Defaults to [].

  • Global attributes are accepted.

Slots

  • label - The label content. Accepts attributes:
    • class (:string)
  • trigger (required) - The trigger button content. Accepts attributes:
    • class (:string)
  • item_indicator - Optional indicator for selected items. Accepts attributes:
    • class (:string)
  • error - Accepts attributes:
    • class (:string)
  • item - Custom content for each item. Receives the item as :let binding. Accepts attributes:
    • class (:string)