Dropdown Showcase
Example
Example is_multiselect
passed in label:
null
Example horiz_selector
Width
null
Component Documentation
Component Name
Dropdown
Builder Function Name
create_dropdown_manager
Description
provides a dropdown or horizontal selector interface to select from an array of options, with optional search support and multi-selection
Use like example
Config
| Property | Type | Default | Description |
|---|---|---|---|
| val | any | the current selection; can be a single value or array for multiselect | |
| options | array | the array of selectable items; each item can be a simple value or an object | |
| on_change | function | callback invoked on each selection, receiving the new val | |
| on_item_click | function | callback invoked whenever an item is clicked, receiving the item object | |
| on_dropdown_opened | function | callback triggered when the dropdown popover is opened | |
| on_dropdown_closed | function | callback triggered when the dropdown popover is closed | |
| on_search | function | optional async callback for searching items, called with { input, id } and returning { options } | |
| label | string | label text displayed above or near the dropdown | |
| type | string | dropdown | mode: 'dropdown' or 'horiz_selector' |
| is_collapsed | boolean | false | if true, operates in 'collapsed' mode for toggling |
| val_key | string | key | key in each option object used to identify the value |
| row_display_keys | array | name | array of keys from which to build a display string for each row |
| button_display_keys | array | name | array of keys used to show text in the dropdown button |
| is_multiselect | boolean | false | if true, multiple values can be selected |
| is_set_null_button | boolean | false | if true, provides a button to clear the selection |
| is_disabled | boolean | false | disables the entire control if true |
| header | string | header text for horizontal selector | |
| header_icon | string | icon id displayed next to header if using horiz_selector | |
| header_icon_deg | number | 0 | icon rotation in degrees for the header icon |
| min_header_width | number | 2 | minimum width (rem) reserved for the header text in horiz_selector |
| spacer_color | string | var(--shadow2-t) | color for the vertical spacer in horiz_selector |
| error_message | string | error text displayed under the label | |
| placeholder | string | Select | placeholder text if no selection is made |
| target_width | number | 250 | popover width in px |
| target_height | number | 200 | popover height in px |
| font_weight | number | 500 | font weight for displayed items |
| font_size | number | 1.2 | font size (rem) for displayed items |
| is_show_x | boolean | false | if true, an x to close the popover is shown |
| text_align | string | left | text alignment for items (left, center, right) |
| justify_content | string | space-between | justification for label+arrow in the default button |
| is_show_arrow | boolean | true | if true, an arrow toggle is shown in the button |
| button_type | string | outlined | style type for the toggle button (primary, outlined, etc.) |
| selected_font_size | number | optional alternate font size used specifically for the selection in the toggle button | |
| is_button_compressed | boolean | false | makes the dropdown button narrower if true |
| is_searchable | boolean | false | if true, shows a text input for filtering or triggering an on_search callback |
| is_hide_button | boolean | false | if true, hides the main toggle button for a fully open experience |
| anchor_id | string | specifies the element id to anchor the popover, or defaults to the toggle button | |
| ml | number | 0 | margin-left in rem for the button |
| mr | number | 0 | margin-right in rem for the button |
| mt | number | 0 | margin-top in rem for the button |
| mb | number | 0 | margin-bottom in rem for the button |
| item_mb | number | 0 | margin-bottom in rem for each dropdown item |
Methods
| Method | Description | Parameters | Returns |
|---|---|---|---|
| init | sets up popover, toggle button, filtering, search input, etc. | config: object | void |
| item_clicked | handles item click logic (single or multi-select), calls on_change and on_item_click if provided | item: object | void |
| set_val | manually sets the current selection val | input: any | void |
| set_options | replaces the current options array; triggers filtered button update | input: array | void |
Returned Properties
| Property | Type | Description |
|---|---|---|
| id | string | unique identifier for this dropdown instance |
| type | string | mode: 'dropdown' or 'horiz_selector' |
| is_collapsed | boolean | if true, collapses the dropdown panel |
| val | any | current single or multi-selection |
| val_key | string | property in options used as the unique key |
| row_display_keys | array | properties used to build displayed text for items |
| button_display_keys | array | properties shown in the toggle button |
| options | array | the array of items displayed in the dropdown |
| is_multiselect | boolean | if true, multiple items can be selected simultaneously |
| is_set_null_button | boolean | if true, includes a 'set to null' button in the dropdown |
| is_disabled | boolean | disables the control if true |
| header | string | header label when in horiz_selector mode |
| header_icon | string | icon id displayed next to the header |
| header_icon_deg | number | rotation in degrees for the header icon |
| min_header_width | number | minimum width in rem for the header region |
| spacer_color | string | color for a vertical spacer in horiz_selector |
| label | string | label text displayed above the dropdown |
| error_message | string | error message displayed |
| placeholder | string | placeholder text if no item is selected |
| target_width | number | popover width in px |
| target_height | number | popover height in px |
| font_weight | number | font weight of the displayed items |
| font_size | number | font size (rem) of the displayed items |
| is_show_x | boolean | if true, displays an 'x' to close the popover |
| text_align | string | alignment for the item text (left, center, right) |
| justify_content | string | how the label and arrow are spaced in the toggle button |
| is_show_arrow | boolean | shows an arrow indicator if true |
| button_type | string | the style type for the toggle button, e.g. 'outlined' |
| selected_font_size | number | alternate font size used specifically for the selected value |
| is_button_compressed | boolean | makes the toggle button narrower if true |
| is_searchable | boolean | if true, shows a search text input for filtering options |
| is_hide_button | boolean | if true, hides the main toggle button |
| item_mb | number | margin-bottom (rem) for each item in the dropdown |
| ml | number | margin-left (rem) for the main button |
| mr | number | margin-right (rem) for the main button |
| mb | number | margin-bottom (rem) for the main button |
| mt | number | margin-top (rem) for the main button |
| search_text_input_manager | object | text input manager used for searching options if is_searchable is true |
| filtered_button_managers | array | the array of dynamically generated button managers for each filtered option |
| popover_manager | object | popover manager controlling the dropdown's popover |
| toggle_button_manager | object | button manager for toggling the popover |
| toggle_button_text | string | the derived text displayed on the toggle button |
| clear_button_manager | object | button manager for clearing the selection (if is_set_null_button is true) |
| header_icon_manager | object | icon manager for the header icon if in horiz_selector mode |
| search_requests_is_loading | array | tracks loading states of async search calls |
