💧 Elixir Only

EO01 · Theme every select from config (no per-instance JS)

config :shadow_styles + <.shadow_styles/> in the layout · opt in with class="elixir-themed"

Set the shared CSS once in config and drop <.shadow_styles/> in your root layout. The wrapper compiles it into one stylesheet and adopts it into every <web-multiselect>'s shadow DOM (adoptedStyleSheets) — which ordinary page CSS can't reach. This theme is scoped with :host(.elixir-themed), so a select opts in just by adding a class.

And it's flash-free: with shared styles configured the wrapper adds upstream's defer attribute (2.1.0) to each select, so it reserves space but builds nothing until the registry has adopted the sheet — then releases the gate. The themed pill badges paint in one shot, with no default-style flash beforehand.

# config/config.exs — configure the shared look ONCE
config :keen_web_multiselect,
  shadow_styles: {:file, "priv/static/assets/ms-elixir-theme.css"}

<%!-- root layout <head>, once --%>
<Keenmate.WebMultiselect.Components.shadow_styles />

/* priv/static/assets/ms-elixir-theme.css */
:host(.elixir-themed) .ms__badge {
  border-radius: 999px;
  background: linear-gradient(135deg, #7c3aed, #ec4899);
  border-color: transparent;
}
:host(.elixir-themed) .ms__badge-text,
:host(.elixir-themed) .ms__badge-remove {
  background: transparent; color: #fff; border-color: transparent;
}

<.web_multiselect
  id="langs"
  class="elixir-themed"
  options={@langs}
  value={["js", "ts", "py"]} />

EO02 · Per-instance theming with CSS variables

pure HEEx style="--ms-…" — scoped to one element, no config, no JS

For a one-off look, set the --ms-* / --base-* custom properties right on the element. Custom properties pierce the shadow DOM, so this needs no callback at all. Prefer this for anything variables can express; reach for the shared adopted-stylesheet theme above only for the arbitrary shadow-DOM CSS residual.

<.web_multiselect
  id="langs"
  style="--ms-accent-color:#0ea5e9; --ms-badge-border-radius:9999px; --ms-input-border-radius:0.5rem;"
  options={@langs}
  value={["go", "rust"]} />

EO03 · Cascading selects (LiveView-driven)

hook="KeenWebMultiselectHook" · server-driven options={@business_units} · push_event "web_multiselect:update"

Three coupled multiselects. Selecting an organization sends a change event through the LV hook; the server looks up the matching business units and pushes the new options back to the dependent select via push_event(socket, "web_multiselect:update", %{id, options, value}). Same flow from unit → department. No inline <script> — the whole cascade is server state.

EO04 · Async search — LiveView tunneled (Elixir fetches GitHub)

search_event="github_search" · server replies {:reply, %{results: [...]}, socket}

Set search_event="github_search" on the wrapper. The hook installs a searchCallback that pushes %{"query" => q, "id" => id} to the LV; the server fetches GitHub, returns {:reply, %{results: [...]}, socket}, and the reply resolves the promise in the browser.

EO05 · Action button → server → selection (with a loader)

hook=true · action-button onClick uses ctx.element.pushToServer · reply → ctx.controller.setSelected(reply.values, { notify: true })

A real-world shape: customers pay online, so statuses settle with a delay. The ⚠️ Payment issues action button doesn't know the answer — it asks the server. Because the lookup takes a second or two, the callback shows a loader (ctx.controller.showMessage(…, { duration: 0 })) while it waits, then selects whatever the reply returns. The button reaches the server through ctx.element.pushToServer — the bridge the hook installs — since action callbacks can't call pushEventTo themselves.

[]

# HEEx — options declarative; hook={true} installs the pushToServer bridge:
<.web_multiselect id="customers" hook={true} multiple options={@customers} />

// JS — the ONE callback on this page. Action-button onClick can't be an attribute
// (it's a function), but the work it triggers is a plain LiveView round-trip:
el.actionButtons = [
  { action: 'custom', text: '⚠️ Payment issues',
    onClick: (_ms, ctx) => {
      ctx.controller.showMessage('Loading recent payment issues…', { duration: 0 }); // loader
      ctx.element.pushToServer('payment_issues', {}, (reply) => {
        ctx.controller.hideMessage();
        ctx.controller.setSelected(reply.values, { notify: true });                   // select
      });
    } },
  { action: 'clear-all', text: 'Clear' },
];

# Elixir — the logic lives here: simulate a 1–2s upstream call, reply with ids:
def handle_event("payment_issues", %{"id" => "customers"}, socket) do
  Process.sleep(1500)
  {:reply, %{values: recent_issue_ids()}, socket}
end

EO06 · Client-side REST — fetch options from an external API (with a header)

hook=true · data-fetch-url="…" · data-fetch-headers={Jason.encode!(%{…})} — no <script>

Sometimes the options live behind a plain HTTP endpoint and there's no reason to relay them through the LiveView. Point the element at the URL with data-fetch-url and the hook fetches it on mount, assigning the JSON straight to options (raw rows are consumed as-is via value_member/display_value_member). It stays fully declarative — the attributes pass through the component's :rest, so there's no per-instance JavaScript.

To add an HTTP header — an API key, an Authorization: Bearer …, a custom X-* — pass data-fetch-headers a JSON object. Crucially the value is rendered server-side from @assigns/config, so a secret is minted in Elixir and never hardcoded into a JS bundle. Here we send a demo X-Demo-Header.

# HEEx — fully declarative. hook={true} installs the data-fetch-* wiring, and the
# element fetches its OWN options from the public API on mount. No <script>, no callback.
<.web_multiselect
  id="rest-users"
  hook={true}
  multiple
  value_member="id"
  display_value_member="name"
  subtitle_member="email"
  placeholder="Loading users…"
  data-fetch-url="https://jsonplaceholder.typicode.com/users"
  data-fetch-headers={Jason.encode!(%{"X-Demo-Header" => "hello-from-elixir"})} />

# The header value is rendered SERVER-SIDE (from assigns/config), so an API key is
# minted in Elixir and never hardcoded in a JS asset:
#   data-fetch-headers={Jason.encode!(%{"Authorization" => "Bearer " <> @api_token})}

EO07 · Client-side REST — an authenticated same-origin API (cookie auth)

data-fetch-url="/api/products?q=price>100" · data-fetch-credentials="same-origin" — the session cookie authenticates it

When the endpoint is your own app, authentication is free. The wrapper's fetch defaults to credentials: "same-origin", so the Phoenix session cookie rides along automatically — the same cookie every other request carries. The API's ordinary session/auth plug pipeline gates it server-side, and no token is ever placed in the DOM. The ?q=price>100 filter is just part of the URL; the controller applies it and returns the matching rows.

# router.ex — a same-origin JSON API. :fetch_session makes the cookie available.
pipeline :api do
  plug :accepts, ["json"]
  plug :fetch_session
end

scope "/api", TestAppWeb.Api do
  pipe_through :api
  get "/products", ProductsController, :index
end

# controller — the browser's fetch used credentials: "same-origin" (the wrapper's
# default), so the Phoenix session cookie arrived with the request. authorize/1 can
# gate on the logged-in user; NO token is exposed in the DOM.
def index(conn, params) do
  case authorize(conn) do
    :ok -> json(conn, filter(@products, params["q"]))
    :unauthorized -> conn |> put_status(:unauthorized) |> json(%{error: "unauthorized"})
  end
end

# HEEx — declarative, hitting our own authed endpoint with a fixed ?q= filter.
<.web_multiselect
  id="rest-products"
  hook={true}
  multiple
  value_member="value"
  display_value_member="label"
  subtitle_member="subtitle"
  placeholder="Loading products over $100…"
  data-fetch-url="/api/products?q=price>100"
  data-fetch-credentials="same-origin" />

# Turn the same endpoint into a live typeahead by switching modes — the hook then
# installs a searchCallback that hits /api/products?q=<typed text>:
#   data-fetch-mode="search"  (query param defaults to "q"; override with
#   data-fetch-query-param="…")