@spec web_multiselect(map()) :: Phoenix.LiveView.Rendered.t()

Renders a <web-multiselect> custom element.

Examples

<.web_multiselect
  id="languages"
  placeholder="Pick a language"
  options={[%{value: "js", label: "JavaScript"}, %{value: "py", label: "Python"}]} />

<.web_multiselect field={@form[:tags]} options={@tag_options} />

LiveView events

When hook={true} is set (see the README), the underlying select, deselect, and change events are forwarded to the server. Listen for them with handle_event/3:

def handle_event("web_multiselect:change", %{"id" => id, "values" => values}, socket) do
  ...
end

To push option or selection changes back from the server, use Keenmate.WebMultiselect.push_update/3.

Attributes

• id (:string) - DOM id; required when used with a LV hook. Defaults to nil.

• field (Phoenix.HTML.FormField) - A Phoenix.HTML.FormField to bind to. Defaults to nil.

• name (:string) - Form field name (overridden by :field if set). Defaults to nil.

• value (:any) - Initial selected value(s). Strings, numbers, list, or nil. Defaults to nil.

• options (:any) - Option list. Accepts:

  • a list of maps with :value/:label (and optional :icon, :subtitle, :group, :disabled)
  • a list of {value, label} tuples
  • a list of arbitrary maps when paired with *_member or get_*_callback props (JS side)

  Defaults to nil.

• hook (:any) - Forwards select/deselect/change events to LiveView. Pass hook={true} for the bundled "KeenWebMultiselectHook", or a string to name a custom hook. false or nil renders no hook. Requires :id.

  Defaults to nil.

• search_event (:string) - Server-side search hook. When set, the LV hook installs a searchCallback on the element that pushes this event name to the LV with %{"query" => q, "id" => id} and awaits a {:reply, %{results: [...]}, socket} response. The results populate the dropdown asynchronously. Requires hook={true}.

  Defaults to nil.

• multiple (:boolean) - Defaults to nil.

• search_placeholder (:string) - Defaults to nil.

• search_hint (:string) - Defaults to nil.

• allow_groups (:boolean) - Defaults to nil.

• show_checkboxes (:boolean) - Defaults to nil.

• show_select_all (:boolean) - Shows upstream's built-in "Select All" action button above the option list (internal: isSelectAllShown). Pairs naturally with show_checkboxes. For finer control over the button row use the action_buttons API instead.

  Defaults to nil.

• checkbox_align (:string) - Defaults to nil.Must be one of nil, "top", "center", or "bottom".

• close_on_select (:boolean) - Defaults to nil.

• dropdown_min_width (:string) - Defaults to nil.

• dropdown_max_width (:string) - Defaults to nil.

• max_height (:string) - Defaults to nil.

• empty_message (:string) - Defaults to nil.

• loading_message (:string) - Defaults to nil.

• select_placeholder (:string) - Placeholder shown when the input isn't a usable search box (enable_search={false}, or search_input_mode is "readonly"/"hidden"). Defaults to "Pick an option..." upstream — set this to override.

  Defaults to nil.

• no_data_placeholder (:string) - Placeholder shown when the option list is empty. Useful for cascade multiselects whose parent isn't resolved yet. Takes priority over placeholder and search_placeholder when the list is empty. Unset by default so async-loaded selects don't flash an empty-state message before their data arrives.

  Defaults to nil.

• badges_display_mode (:string) - Defaults to nil.Must be one of nil, "badges", "count", "compact", "partial", or "none".

• badges_threshold (:integer) - Defaults to nil.

• badges_threshold_mode (:string) - Defaults to nil.Must be one of nil, "count", or "partial".

• badges_max_visible (:integer) - Defaults to nil.

• badges_position (:string) - Defaults to nil.Must be one of nil, "top", "bottom", "left", or "right".

• show_counter (:boolean) - Defaults to nil.

• enable_badge_tooltips (:boolean) - Defaults to nil.

• badge_tooltip_placement (:string) - Defaults to nil.Must be one of nil, "top", "top-start", "top-end", "bottom", "bottom-start", "bottom-end", "left", "left-start", "left-end", "right", "right-start", or "right-end".

• badge_tooltip_delay (:integer) - Defaults to nil.

• badge_tooltip_offset (:integer) - Defaults to nil.

• remove_button_tooltip_text (:string) - Format string for the remove-button tooltip. {0} interpolates the item name. Defaults to "Remove {0}" upstream. Defaults to nil.

• enable_option_tooltips (:boolean) - Show a hover tooltip on each dropdown option row. Default content is the option's display value, plus its subtitle on a second line when present. Override per option with the JS-side getOptionTooltipCallback. Off by default upstream.

  Defaults to nil.

• option_tooltip_placement (:string) - Placement relative to the option row. Defaults to "top-start" upstream (anchored to the row's start edge). Use left/right for a narrow control's side. Defaults to nil. Must be one of nil, "top", "top-start", "top-end", "bottom", "bottom-start", "bottom-end", "left", "left-start", "left-end", "right", "right-start", or "right-end".

• option_tooltip_follow_cursor (:boolean) - Anchor the option tooltip to the mouse pointer and follow it across the row. Useful for very wide rows. Defaults to false upstream. Defaults to nil.

• option_tooltip_delay (:integer) - Show/hide delay in ms. Falls back to badge_tooltip_delay, then 100 upstream. Defaults to nil.

• option_tooltip_offset (:integer) - Tooltip offset in px from the row. Falls back to badge_tooltip_offset, then 8 upstream. Defaults to nil.

• enable_search (:boolean) - Defaults to nil.

• search_input_mode (:string) - Defaults to nil.Must be one of nil, "normal", "readonly", or "hidden".

• search_mode (:string) - Defaults to nil.Must be one of nil, "filter", or "navigate".

• min_search_length (:integer) - Defaults to nil.

• keep_options_on_search (:boolean) - Defaults to nil.

• should_keep_search_on_close (:boolean) - Defaults to nil.

• allow_add_new (:boolean) - Defaults to nil.

• search_debounce (:integer) - Debounce delay in milliseconds before the async searchCallback fires. A burst of keystrokes collapses into a single request instead of one per character. Applies to the async path only — local in-memory filtering stays instant. Defaults to 0 (no debounce) upstream.

  Defaults to nil.

• sticky_actions (:boolean) - Defaults to nil.

• actions_layout (:string) - Defaults to nil.Must be one of nil, "nowrap", or "wrap".

• actions_position (:string) - Render the action-buttons block as a sticky header ("top", default) or footer ("bottom"). Defaults to nil. Must be one of nil, "top", or "bottom".

• actions_align (:string) - Horizontal arrangement of buttons within a row. "stretch" (default) keeps full-width; the others size buttons to content and distribute them. Defaults to nil. Must be one of nil, "stretch", "left", "right", "center", or "space-between".

• lock_placement (:boolean) - Defaults to nil.

• value_member (:string) - Defaults to nil.

• display_value_member (:string) - Defaults to nil.

• search_value_member (:string) - Defaults to nil.

• icon_member (:string) - Defaults to nil.

• subtitle_member (:string) - Defaults to nil.

• group_member (:string) - Defaults to nil.

• disabled_member (:string) - Defaults to nil.

• value_format (:string) - Defaults to nil.Must be one of nil, "json", "csv", or "array".

• initial_values (:any) - Pre-selected values. List/term; encoded as JSON for the underlying attribute. Defaults to nil.

• enable_virtual_scroll (:boolean) - Defaults to nil.

• virtual_scroll_threshold (:integer) - Defaults to nil.

• option_height (:integer) - Defaults to nil.

• badge_height (:integer) - Pixel height per badge row in the popover virtual-scroll list. Defaults to 36 upstream. Defaults to nil.

• virtual_scroll_buffer (:integer) - Defaults to nil.

• placeholder (:string) - Placeholder shown when no item is selected (passthrough). Defaults to nil.

• class (:string) - Defaults to nil.

• style (:string) - Defaults to nil.

• show_debug_info (:boolean) - Toggles upstream's .ms__debug-info stats panel inside the shadow DOM. Reactive — flipping between renders adds/removes the panel without reinitializing the component. Useful while diagnosing virtual-scroll thresholds, search timing, and option-list growth.

  Defaults to nil.

• Global attributes are accepted. Any extra HTML / phx-* attribute; passed through verbatim.

Slots

• inner_block - Optional declarative <option> / <optgroup> markup.