README

This extension wraps a Bootstrap dropdown into a reusable JavaScript class (Dropdown) and adds:

a searchable dropdown input
a hidden input for stable form values
dynamic item loading/replacement
programmatic selection and reset
optional swipe actions per item
optional List.js integration

Purpose and Use Cases

Use this when a plain Bootstrap dropdown is not enough, for example:

large selectable lists with live filtering
forms that must submit a stable value (key) through a hidden field
dynamic data sources (Ajax/reload) without rebuilding markup manually
extra interactions such as swipe delete or preselection

Requirements

Bootstrap 5 (or 4 via the built-in window.bs4 fallback)
jQuery (used internally)
optional: List.js when using listjs: true

Quick Start

HTML:

<div id="countryDropdown"></div>

JavaScript:

const dd = new Dropdown('countryDropdown', {
  placeholder: 'Select country',
  items: {
    de: { description: 'Germany' },
    at: { description: 'Austria' },
    ch: { description: 'Switzerland' }
  },
  onSelected: () => {
    const selected = dd.selected();
    console.log('Selected:', selected?.key, selected?.description);
  }
});

The selected value is stored in the hidden input with name="countryDropdown".

Initialization: Full Options List

const dd = new Dropdown('exampleDropdown', {
  bootstrapmajor: 5,
  buttonstyle: 'btn-outline-secondary',
  caret: true,
  disabled: false,
  floatingbox: false,
  items: {},
  listjs: false,
  filter: true,
  menumaxheight: '300px',
  menustyle: '',
  placeholder: '',
  required: false,
  swipe: {
    left: {
      hint: false,
      action: false,
      condition: (idx, item, li) => true
    },
    right: {
      hint: false,
      action: false,
      condition: (idx, item, li) => true
    }
  },
  onSelected: e => {},
  onInput: (event, input) => {},
  onReplaceText: undefined,
  item: '<li>Entry</li>',
  valueNames: [],
  valueKey: undefined,
  bootstrapAutoClose: undefined
});

Option	Type	Default	Description
`bootstrapmajor`	`number`	`5`	Bootstrap major version (`5` or `4`).
`buttonstyle`	`string`	`'btn-outline-secondary'`	Extra classes on the toggle button.
`caret`	`boolean`	`true`	Shows/hides the caret on the button (`false` disables it).
`disabled`	`boolean`	`false`	Disables input, toggle, and hidden input.
`floatingbox`	`boolean`	`false`	Enables Bootstrap floating-label behavior (with `filter: true`).
`items`	`object`	`{}`	Initial entries. Keys become `data-value` / hidden-input value.
`listjs`	`boolean`	`false`	Enables List.js mode instead of native menu rendering.
`filter`	`boolean`	`true`	Enables/disables searchable input (`false` = button label only).
`menumaxheight`	`string`	`'300px'`	Menu max-height (inline style).
`menustyle`	`string`	`''`	Additional inline style for the menu.
`placeholder`	`string`	`''`	Placeholder for search input or label placeholder when `filter: false`.
`required`	`boolean`	`false`	Sets `required` on the search input.
`swipe.left.hint`	`string\|false`	`false`	HTML hint for left swipe (for example an icon).
`swipe.left.action`	`function\|false`	`false`	Callback on valid left swipe (`(event, li) => {}`).
`swipe.left.condition`	`function`	`(item) => true`	Condition to allow left swipe (`(idx, item, li) => boolean`).
`swipe.right.hint`	`string\|false`	`false`	HTML hint for right swipe.
`swipe.right.action`	`function\|false`	`false`	Callback on valid right swipe (`(event, li) => {}`).
`swipe.right.condition`	`function`	`(item) => true`	Condition to allow right swipe (`(idx, item, li) => boolean`).
`onSelected`	`function`	`(e) => {}`	Runs after an item is selected.
`onInput`	`function`	`(event, input) => {}`	Runs while typing/filtering.
`onReplaceText`	`function\|undefined`	`undefined`	Overrides default display-text replacement (click/focusout).
`item`	`string`	`'<li>Entry</li>'`	List.js item template (`listjs: true`).
`valueNames`	`array`	`[]`	List.js field definitions (`listjs: true`).
`valueKey`	`string\|undefined`	`auto`	Forces which List.js item field is used as internal key.
`bootstrapAutoClose`	`boolean\|undefined`	`undefined`	Relevant only for Bootstrap 4 fallback; `false` prevents `hide.bs.dropdown`.

Item Structure

A single items entry currently supports:

items: {
  de: {
    description: 'Germany', // string | Element | { short, extended }
    disabled: false,        // optional
    active: false,          // optional, marks item as active/preselected
    selected: false,        // optional
    dataList: {             // optional extra attributes for item button
      'data-country-code': 'DE'
    }
  }
}

Usage Snippets

1. Set items dynamically

dd.setItems({
  fr: { description: 'France' },
  it: { description: 'Italy' }
});

2. Select programmatically

await dd.selected('it'); // triggers click on item with key "it"

3. Clear selection / input

dd.clear({
  resetSelection: true,
  resetInput: true,
  close: true
});

4. Disable/enable dropdown

dd.setDisabled(true);  // disable
dd.setDisabled(false); // enable

5. Swipe action on list entries

const taskDd = new Dropdown('taskDropdown', {
  items: {
    1: { description: 'Task A' },
    2: { description: 'Task B' }
  },
  swipe: {
    left: {
      hint: '<i class="bi bi-trash"></i>',
      action: (event, li) => {
        console.log('Delete:', li);
        return true; // true => entry is removed with animation
      }
    }
  }
});

6. Dispose cleanly (for example before DOM removal)

dd.dispose();

Important Methods (Short Overview)

setItems(items, callback?, options?): add new entries / re-render
selected(): get currently selected item
selected(key): select item by key
selected(null): clear current selection
clear(options?): clear items/selection in a controlled way
setDisabled(state): enable/disable interaction
getInput(): current visible input text
matchItem(): number of exact matches for current input
dispose(): remove listeners/instance safely

Notes

With filter: false, the component uses a button label instead of a search input.
When listjs: true, List.js must be available, otherwise initialization is incomplete.
The container dispatches custom events including dropdown-items-rendered.

braesident / dropdown

Maintainers

Package info

Statistics

Security