@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.

Attribute defaults

Every attribute defaults to nil, which means "don't emit it" — the underlying component's own default then applies. The docs below note the upstream default where it's useful to know. See the upstream usage docs for the full behavior of each option.

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) - Allow selecting more than one option. Defaults to true upstream — set false for a single-select. Defaults to nil.

• search_placeholder (:string) - Placeholder text for the search/filter input inside the dropdown. Defaults to nil.

• search_hint (:string) - Hint line shown near the search input to guide the user (e.g. "Type to filter…"). Defaults to nil.

• allow_groups (:boolean) - Render options grouped by their group_member (optgroup-style headers). Off by default. Defaults to nil.

• show_checkboxes (:boolean) - Render a checkbox in each option row. Off by default. 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) - Vertical alignment of each option's checkbox within its row. Defaults to nil. Must be one of nil, "top", "center", or "bottom".

• close_on_select (:boolean) - Close the dropdown after a selection is made (typical for single-select). Defaults to nil.

• dropdown_min_width (:string) - Minimum width of the dropdown panel, as a CSS length (e.g. "320px"). Defaults to nil.

• dropdown_max_width (:string) - Maximum width of the dropdown panel, as a CSS length. Defaults to nil.

• max_height (:string) - Maximum height of the option list before it scrolls, as a CSS length. Defaults to nil.

• empty_message (:string) - Message shown when there are no options to display. Defaults to nil.

• loading_message (:string) - Message shown while async options are loading. 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) - How selected items appear in the control: badges (default), count, compact, partial, or none. Defaults to nil. Must be one of nil, "badges", "count", "compact", "partial", or "none".

• badges_threshold (:integer) - Selected-count at which the display collapses to the badges_threshold_mode summary. Defaults to nil.

• badges_threshold_mode (:string) - How to summarize once badges_threshold is exceeded — count or partial. Defaults to nil. Must be one of nil, "count", or "partial".

• badges_max_visible (:integer) - Maximum number of badges rendered before the remainder collapse into a summary. Defaults to nil.

• badges_position (:string) - Where the badges render relative to the input. Defaults to nil. Must be one of nil, "top", "bottom", "left", or "right".

• show_counter (:boolean) - Show a count of the selected items. Defaults to nil.

• enable_badge_tooltips (:boolean) - Show a tooltip with the full label when hovering a badge. Off by default. Defaults to nil.

• badge_tooltip_placement (:string) - Placement of the badge tooltip (a Floating-UI placement). 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) - Show/hide delay for badge tooltips, in milliseconds. Defaults to nil.

• badge_tooltip_offset (:integer) - Distance of the badge tooltip from the badge, in pixels. 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) - Show the search/filter input inside the dropdown. On by default upstream. Defaults to nil.

• search_input_mode (:string) - Search input behavior: normal, readonly, or hidden. When not usable, select_placeholder shows. Defaults to nil. Must be one of nil, "normal", "readonly", or "hidden".

• search_mode (:string) - What typing does: filter narrows the list, navigate jumps to matching rows without hiding others. Defaults to nil. Must be one of nil, "filter", or "navigate".

• min_search_length (:integer) - Minimum number of characters before searching/filtering kicks in. Defaults to nil.

• keep_options_on_search (:boolean) - Keep the full option list visible while searching instead of filtering it down. Defaults to nil.

• should_keep_search_on_close (:boolean) - Preserve the search text when the dropdown closes instead of clearing it. Defaults to nil.

• allow_add_new (:boolean) - Allow creating a new option from the search text when nothing matches. 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) - Keep the action-buttons row pinned while the option list scrolls. Defaults to nil.

• actions_layout (:string) - Whether action buttons stay on a single row (nowrap) or wrap onto multiple rows (wrap). 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) - Lock the dropdown's placement instead of auto-flipping/shifting to fit the viewport. Defaults to nil.

• value_member (:string) - Object key to read each option's value from. The wrapper defaults this to "value". Defaults to nil.

• display_value_member (:string) - Object key for each option's display label. The wrapper defaults this to "label". Defaults to nil.

• search_value_member (:string) - Object key for the text search matches against. Not defaulted — falls back to the display value upstream. Defaults to nil.

• icon_member (:string) - Object key for an option's icon. The wrapper defaults this to "icon". Defaults to nil.

• subtitle_member (:string) - Object key for an option's secondary line. The wrapper defaults this to "subtitle". Defaults to nil.

• group_member (:string) - Object key for an option's group name (used when allow_groups). The wrapper defaults this to "group". Defaults to nil.

• disabled_member (:string) - Object key marking an option disabled. The wrapper defaults this to "disabled". Defaults to nil.

• value_format (:string) - How selected values are serialized into the hidden form input: json, csv, or array. 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) - Enable windowed rendering of the option list so large datasets stay fast. Defaults to nil.

• virtual_scroll_threshold (:integer) - Option count above which virtual scrolling activates automatically. Defaults to nil.

• option_height (:integer) - Fixed pixel height of each option row — required for the virtual-scroll offset math. 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) - Extra rows rendered above and below the viewport while virtual-scrolling. Defaults to nil.

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

• class (:string) - CSS class(es) applied to the <web-multiselect> element. Defaults to nil.

• style (:string) - Inline style applied to the <web-multiselect> element. 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.