# Dropdown — SvelteKit UI

Package: sveltekit-ui 1.1.94

Page: https://www.sveltekit-ui.com/components/dropdown

Category: Input controls

provides a dropdown or horizontal selector interface to select from an array of options, with optional search support and multi-selection

Public component import: `Dropdown`

Public manager import: `create_dropdown_manager`

## Usage

```svelte
<script>
  // Import the shared stylesheet once in your application's root layout.
  import "sveltekit-ui/style.css"
  import { Dropdown, create_dropdown_manager } from "sveltekit-ui"

  const manager = create_dropdown_manager({
    label: "Project status",
    val: "draft",
    options: [
      { key: "draft", name: "Draft" },
      { key: "review", name: "In review" },
      { key: "published", name: "Published" },
    ],
    is_searchable: true,
  })
</script>

<Dropdown {manager} />
<p>Selected: {manager.val}</p>
```

## Configuration

### `val`

- type: any
- default: null
- description: the current selection; can be a single value or array for multiselect

### `options`

- type: array
- default:
- description: the array of selectable items; each item can be a simple value or an object

### `on_change`

- type: function
- default: null
- description: callback invoked on each selection, receiving the new val

### `on_item_click`

- type: function
- default: null
- description: callback invoked whenever an item is clicked, receiving the item object

### `on_dropdown_opened`

- type: function
- default: null
- description: callback triggered when the dropdown popover is opened

### `on_dropdown_closed`

- type: function
- default: null
- description: callback triggered when the dropdown popover is closed

### `on_search`

- type: function
- default: null
- description: optional async callback for searching items, called with { input, id } and returning { options }

### `label`

- type: string
- default: null
- description: label text displayed above or near the dropdown

### `type`

- type: string
- default: dropdown
- description: mode: 'dropdown' or 'horiz_selector'

### `is_collapsed`

- type: boolean
- default: false
- description: if true, operates in 'collapsed' mode for toggling

### `val_key`

- type: string
- default: key
- description: key in each option object used to identify the value

### `row_display_keys`

- type: array
- default:
  - name
- description: array of keys from which to build a display string for each row

### `button_display_keys`

- type: array
- default:
  - name
- description: array of keys used to show text in the dropdown button

### `is_multiselect`

- type: boolean
- default: false
- description: if true, multiple values can be selected

### `is_set_null_button`

- type: boolean
- default: false
- description: if true, provides a button to clear the selection

### `is_disabled`

- type: boolean
- default: false
- description: disables the entire control if true

### `header`

- type: string
- default: null
- description: header text for horizontal selector

### `header_icon`

- type: string
- default: null
- description: icon id displayed next to header if using horiz_selector

### `header_icon_deg`

- type: number
- default: 0
- description: icon rotation in degrees for the header icon

### `min_header_width`

- type: number
- default: 2
- description: minimum width (rem) reserved for the header text in horiz_selector

### `spacer_color`

- type: string
- default: var(--shadow2-t)
- description: color for the vertical spacer in horiz_selector

### `error_message`

- type: string
- default: null
- description: error text displayed under the label

### `placeholder`

- type: string
- default: Select
- description: placeholder text if no selection is made

### `target_width`

- type: number
- default: 250
- description: popover width in px

### `target_height`

- type: number
- default: 200
- description: popover height in px

### `font_weight`

- type: number
- default: 500
- description: font weight for displayed items

### `font_size`

- type: number
- default: 1.2
- description: font size (rem) for displayed items

### `is_show_x`

- type: boolean
- default: false
- description: if true, an x to close the popover is shown

### `text_align`

- type: string
- default: left
- description: text alignment for items (left, center, right)

### `justify_content`

- type: string
- default: space-between
- description: justification for label+arrow in the default button

### `is_show_arrow`

- type: boolean
- default: true
- description: if true, an arrow toggle is shown in the button

### `button_type`

- type: string
- default: outlined
- description: style type for the toggle button (primary, outlined, etc.)

### `selected_font_size`

- type: number
- default: null
- description: optional alternate font size used specifically for the selection in the toggle button

### `is_button_compressed`

- type: boolean
- default: false
- description: makes the dropdown button narrower if true

### `is_searchable`

- type: boolean
- default: false
- description: if true, shows a text input for filtering or triggering an on_search callback

### `is_hide_button`

- type: boolean
- default: false
- description: if true, hides the main toggle button for a fully open experience

### `anchor_id`

- type: string
- default: null
- description: specifies the element id to anchor the popover, or defaults to the toggle button

### `ml`

- type: number
- default: 0
- description: margin-left in rem for the button

### `mr`

- type: number
- default: 0
- description: margin-right in rem for the button

### `mt`

- type: number
- default: 0
- description: margin-top in rem for the button

### `mb`

- type: number
- default: 0
- description: margin-bottom in rem for the button

### `item_mb`

- type: number
- default: 0
- description: margin-bottom in rem for each dropdown item

## Methods

### `init()`

- description: sets up popover, toggle button, filtering, search input, etc.
- parameters:
  - config: object
- returns: void

### `item_clicked()`

- description: handles item click logic (single or multi-select), calls on_change and on_item_click if provided
- parameters:
  - item: object
- returns: void

### `set_val()`

- description: manually sets the current selection val
- parameters:
  - input: any
- returns: void

### `set_options()`

- description: replaces the current options array; triggers filtered button update
- parameters:
  - input: array
- returns: void

## Returned state

### `id`

- type: string
- description: unique identifier for this dropdown instance

### `type`

- type: string
- description: mode: 'dropdown' or 'horiz_selector'

### `is_collapsed`

- type: boolean
- description: if true, collapses the dropdown panel

### `val`

- type: any
- description: current single or multi-selection

### `val_key`

- type: string
- description: property in options used as the unique key

### `row_display_keys`

- type: array
- description: properties used to build displayed text for items

### `button_display_keys`

- type: array
- description: properties shown in the toggle button

### `options`

- type: array
- description: the array of items displayed in the dropdown

### `is_multiselect`

- type: boolean
- description: if true, multiple items can be selected simultaneously

### `is_set_null_button`

- type: boolean
- description: if true, includes a 'set to null' button in the dropdown

### `is_disabled`

- type: boolean
- description: disables the control if true

### `header`

- type: string
- description: header label when in horiz_selector mode

### `header_icon`

- type: string
- description: icon id displayed next to the header

### `header_icon_deg`

- type: number
- description: rotation in degrees for the header icon

### `min_header_width`

- type: number
- description: minimum width in rem for the header region

### `spacer_color`

- type: string
- description: color for a vertical spacer in horiz_selector

### `label`

- type: string
- description: label text displayed above the dropdown

### `error_message`

- type: string
- description: error message displayed

### `placeholder`

- type: string
- description: placeholder text if no item is selected

### `target_width`

- type: number
- description: popover width in px

### `target_height`

- type: number
- description: popover height in px

### `font_weight`

- type: number
- description: font weight of the displayed items

### `font_size`

- type: number
- description: font size (rem) of the displayed items

### `is_show_x`

- type: boolean
- description: if true, displays an 'x' to close the popover

### `text_align`

- type: string
- description: alignment for the item text (left, center, right)

### `justify_content`

- type: string
- description: how the label and arrow are spaced in the toggle button

### `is_show_arrow`

- type: boolean
- description: shows an arrow indicator if true

### `button_type`

- type: string
- description: the style type for the toggle button, e.g. 'outlined'

### `selected_font_size`

- type: number
- description: alternate font size used specifically for the selected value

### `is_button_compressed`

- type: boolean
- description: makes the toggle button narrower if true

### `is_searchable`

- type: boolean
- description: if true, shows a search text input for filtering options

### `is_hide_button`

- type: boolean
- description: if true, hides the main toggle button

### `item_mb`

- type: number
- description: margin-bottom (rem) for each item in the dropdown

### `ml`

- type: number
- description: margin-left (rem) for the main button

### `mr`

- type: number
- description: margin-right (rem) for the main button

### `mb`

- type: number
- description: margin-bottom (rem) for the main button

### `mt`

- type: number
- description: margin-top (rem) for the main button

### `search_text_input_manager`

- type: object
- description: text input manager used for searching options if is_searchable is true

### `filtered_button_managers`

- type: array
- description: the array of dynamically generated button managers for each filtered option

### `popover_manager`

- type: object
- description: popover manager controlling the dropdown's popover

### `toggle_button_manager`

- type: object
- description: button manager for toggling the popover

### `toggle_button_text`

- type: string
- description: the derived text displayed on the toggle button

### `clear_button_manager`

- type: object
- description: button manager for clearing the selection (if is_set_null_button is true)

### `header_icon_manager`

- type: object
- description: icon manager for the header icon if in horiz_selector mode

### `search_requests_is_loading`

- type: array
- description: tracks loading states of async search calls
