COMPONENT REFERENCE — <.web_multiselect> ======================================== `Keenmate.WebMultiselect.Components.web_multiselect/1` declares a typed `attr/3` for every documented upstream attribute. For the authoritative, always-current list with per-attribute docs and defaults, see the generated hexdocs for `web_multiselect/1`. This file is the orientation map. HOW ATTRIBUTES MAP ------------------ 1. snake_case in HEEx -> kebab-case on the element: search_placeholder -> search-placeholder badges_display_mode -> badges-display-mode 2. BOOLEANS render as explicit "true"/"false" strings, NOT HTML presence. Reason: several upstream booleans default to true, so you need a real opt-out. multiple={false} -> multiple="false" show_checkboxes={true} -> show-checkboxes="true" 3. nil means OMIT. Any attr left at its nil default is not emitted, so the upstream default applies. Only pass what you want to change. 4. `class`, `style`, and any `data-*` / `phx-*` attribute pass straight through (`style` and `class` land on the element; use them for per-instance CSS variables and dark-mode, see theming.txt). IDENTITY / DATA --------------- id - element id; also triggers phx-update="ignore" (see server-updates.txt) field - a Phoenix.HTML.FormField; fills id/name/value (see forms.txt) name - hidden input name (usually from `field`) value - current selection, a list (e.g. ["py"]); flows to initial-values options - option list (maps or {value,label} tuples; see data-and-options.txt) initial_values- explicit initial selection if not using `value` WRAPPER / LIVEVIEW (not upstream HTML attrs) -------------------------------------------- hook - true | "CustomHook" | false. true => "KeenWebMultiselectHook". Enables select/deselect/change events. (liveview-events.txt) search_event - event name for server-side search over the LV channel. Requires the hook. (server-search.txt) BEHAVIOR -------- multiple - allow multiple selection (upstream default true; false = single) enable_search - show the search box (default true) search_mode - filter vs navigate behavior search_input_mode min_search_length keep_options_on_search should_keep_search_on_close allow_add_new - allow creating a new option from the query search_debounce - ms to collapse keystroke bursts (server-search.txt) close_on_select allow_groups - honor an option `group` member and render optgroup-style groups show_checkboxes show_select_all checkbox_align - top | center | bottom lock_placement PLACEHOLDERS / MESSAGES ----------------------- placeholder search_placeholder search_hint select_placeholder - shown for non-searchable pickers no_data_placeholder - shown when the option list is empty empty_message loading_message BADGES / SELECTED DISPLAY ------------------------- badges_display_mode - how selected items render (pills, count, etc.) badges_threshold badges_threshold_mode badges_max_visible badges_position show_counter show_badge_full_title - render each badge's full_title_member breadcrumb instead of the display value (tree mode; see below) remove_button_tooltip_text (supports {0} interpolation) enable_badge_tooltips, badge_tooltip_placement, badge_tooltip_delay, badge_tooltip_offset OPTION TOOLTIPS --------------- enable_option_tooltips option_tooltip_placement - Floating-UI placement, default top-start option_tooltip_follow_cursor option_tooltip_delay option_tooltip_offset ACTION BUTTONS -------------- sticky_actions actions_layout actions_position - top | bottom actions_align - stretch | left | right | center | space-between MEMBER MAPPING (map your data's keys -> component roles) -------------------------------------------------------- value_member (wrapper default "value") display_value_member (wrapper default "label") icon_member (default "icon") subtitle_member (default "subtitle") group_member (default "group") disabled_member (default "disabled") search_value_member (NOT defaulted — set it to search a different field) See data-and-options.txt. Because the wrapper defaults the six canonical members on every render, plain %{value:, label:} options "just work". SIZING / LAYOUT --------------- max_height dropdown_min_width, dropdown_max_width dropdown_width - width of the options dropdown, decoupled from the input. String CSS length; sugar over --ms-dropdown-width (default: tracks the input width). selected_popover_width - width of the "N selected" popover. String CSS length; sugar over --ms-selected-popover-width (default 32rem). For proportional scaling use the CSS var --ms-rem (theming.txt), not an attr. See theming.txt / guides/theming.md "Independent panel widths". TREE OF OPTIONS / CASCADE CHECKBOXES ------------------------------------ Give options a materialized dot-path and the list renders as an always-expanded hierarchy. Setting path_member ENABLES tree mode. Full guide: guides/tree_of_options.md. path_member - key holding the dot-path ("1", "1.1", "1.1.1"). Setting it turns on tree mode; parent/level are derived from the path. parent_path_member - key holding the parent path (optional; derived when unset) level_member - key holding the depth/level (optional; derived when unset) has_children_member - key holding a precomputed hasChildren flag (optional) is_selectable_member - boolean key; a falsy value makes a node NON-selectable (renders normally, no checkbox, skipped by Select All / keyboard). NOT the same as disabled (which greys out). tree_path_separator - path separator (default ".") checkbox_mode - "independent" (default) | "cascade". Cascade checks a node's whole subtree; a partial branch shows a tristate box. cascade_select_policy - which values a cascade selection emits (badges/form/change): "rolled-up" (default, minimal cover) | "leaves" | "all". full_title_member - key holding a fully-qualified breadcrumb label; pair with show_badge_full_title (see BADGES). Never computed. VIRTUAL SCROLLING (large lists) ------------------------------- enable_virtual_scroll virtual_scroll_threshold virtual_scroll_buffer option_height badge_height FORM / VALUE ENCODING --------------------- value_format - how the hidden input serializes the value (see forms.txt) STYLING PASSTHROUGH ------------------- class, style - applied to the element rest (:global) - any extra HTML / phx-* / data-* attribute, verbatim Full per-attribute descriptions + exact defaults: hexdocs `web_multiselect/1`. Upstream semantics for what each does: https://github.com/keenmate/web-multiselect/blob/main/docs/usage.md