@stackline/multiselect

A maintained vanilla JavaScript multiselect dropdown for framework-agnostic UI workflows, with search, grouping, selection limits, item and badge templates, direct browser usage, and switchable Stackline skins.

Documentation & Live Demos | Direct Download | npm | Issues | Repository

Latest npm release: 1.0.3 for vanilla JavaScript projects

Credits: Current maintenance, vanilla package stewardship, publishing, and documentation by Alexandro Paixao Marques.

Why this library?

@stackline/multiselect is for projects that need a reliable multiselect without a framework dependency. It works with plain HTML, server-rendered pages, static sites, CMS templates, and framework apps that prefer to mount a small browser widget directly.

The package ships a single JavaScript file, a single CSS file, built-in skins, and a direct download bundle for projects that do not use npm.

Features

Table of Contents

1. Vanilla Version Note
2. Installation
3. Direct Download
4. Setup
5. Basic Usage
6. Official Vanilla Test Matrix
7. Settings
8. Skins and Themes
9. Custom Skins
10. Custom Templates
11. Events
12. API
13. Run Locally
14. License

Vanilla Version Note

• package: @stackline/multiselect
• runtime: plain browser JavaScript
• global constructor: StacklineMultiSelect
• dependencies: none
• current published line: 1.0.x

This vanilla package is separate from the Angular package. Use @stackline/multiselect when you need direct browser usage without Angular, React, Vue, or a bundler.

Installation

npm install @stackline/multiselect

Install the current tested vanilla release exactly:

npm install @stackline/multiselect@1.0.3 --save-exact

Direct Download

Use the direct download when your project does not use npm:

https://github.com/alexandroit/stackline-multiselect/releases/download/v1.0.3/stackline-multiselect-1.0.3.zip

Extract the archive and copy these files into your public assets:

stackline-multiselect.css
stackline-multiselect.js
direct-example.html

Setup

1. Add the stylesheet

<link rel="stylesheet" href="./stackline-multiselect.css">

When installing with npm, reference the package file or copy it into your app assets:

<link rel="stylesheet" href="./node_modules/@stackline/multiselect/src/stackline-multiselect.css">

2. Add a mount element

<div id="countries"></div>

3. Add the browser script

<script src="./stackline-multiselect.js"></script>

For npm installs:

<script src="./node_modules/@stackline/multiselect/src/stackline-multiselect.js"></script>

Basic Usage

<link rel="stylesheet" href="./stackline-multiselect.css">

<div id="countries"></div>

<script src="./stackline-multiselect.js"></script>
<script>
  var dropdown = new StacklineMultiSelect("#countries", {
    data: [
      { id: 1, itemName: "Brazil" },
      { id: 2, itemName: "Canada" },
      { id: 3, itemName: "Portugal" },
      { id: 4, itemName: "United States" }
    ],
    selected: [{ id: 2, itemName: "Canada" }],
    settings: {
      singleSelection: false,
      text: "Select countries",
      selectAllText: "Select all",
      unSelectAllText: "Clear all",
      enableSearchFilter: true,
      searchPlaceholderText: "Search",
      badgeShowLimit: 4,
      maxHeight: 260,
      showCheckbox: true,
      showClearAll: true,
      noDataLabel: "No data",
      theme: "classic",
      skin: "classic"
    }
  });
</script>

Official Vanilla Test Matrix

The public documentation uses the same examples from the vanilla test application. Switch between skins through the settings object:

settings: {
  text: "Classic basic",
  theme: "classic",
  skin: "classic"
}

settings: {
  text: "Material basic",
  theme: "material",
  skin: "material"
}

The same scenarios are validated for classic, material, dark, and custom skins:

Settings

settings: {
  idKey: "id",
  labelKey: "itemName",
  singleSelection: false,
  text: "Select",
  selectAllText: "Select all",
  unSelectAllText: "Clear all",
  clearAllText: "Clear selected items",
  enableCheckAll: true,
  enableSearchFilter: true,
  searchPlaceholderText: "Search",
  badgeShowLimit: 4,
  showClearAll: true,
  maxHeight: 260,
  showCheckbox: true,
  noDataLabel: "No data",
  theme: "classic",
  skin: "classic",
  disabled: false,
  groupBy: "",
  limitSelection: 0,
  lazyLoading: false
}

Skins and Themes

Built-in skins:

• classic
• material
• dark
• custom

Switch the skin at runtime:

dropdown.setTheme("dark");

You can also update only the settings object:

dropdown.setSettings({
  theme: "material",
  skin: "material"
});

The component adds theme-{name} to the internal .stackline-dropdown root.

Custom Skins

Use custom when you want the variable-driven layout without naming a new skin:

dropdown.setTheme("custom");

Use any other name when your app needs a named brand skin. Names outside the built-in skins automatically receive both theme-{name} and theme-custom.

dropdown.setTheme("brand");

.stackline-dropdown.theme-brand {
  --stackline-ms-primary: #7c3aed;
  --stackline-ms-primary-soft: rgba(124, 58, 237, 0.14);
  --stackline-ms-surface: #ffffff;
  --stackline-ms-surface-soft: #f5f3ff;
  --stackline-ms-surface-muted: #ede9fe;
  --stackline-ms-outline: #c4b5fd;
  --stackline-ms-outline-strong: #7c3aed;
  --stackline-ms-on-surface: #22183f;
  --stackline-ms-on-surface-muted: #6b5d80;
  --stackline-ms-chip-bg: #ede9fe;
  --stackline-ms-chip-text: #5b21b6;
  --stackline-ms-chip-remove: #5b21b6;
  --stackline-ms-divider: rgba(124, 58, 237, 0.16);
  --stackline-ms-section-bg: #faf5ff;
}

Custom Templates

new StacklineMultiSelect("#colors", {
  data: colors,
  selected: [],
  settings: {
    text: "Select colors",
    theme: "material",
    skin: "material"
  },
  badgeTemplate: function (item) {
    return '<span class="chip">' + item.itemName + '</span>';
  },
  itemTemplate: function (item) {
    return '<strong>' + item.itemName + '</strong><small>' + item.detail + '</small>';
  }
});

Events

var dropdown = new StacklineMultiSelect("#countries", {
  data: countries,
  selected: [],
  settings: { theme: "material", skin: "material" },
  onSelect: function (item, instance) {},
  onDeSelect: function (item, instance) {},
  onSelectAll: function (items, instance) {},
  onDeSelectAll: function (items, instance) {},
  onChange: function (items, instance) {},
  onOpen: function (items, instance) {},
  onClose: function (items, instance) {}
});

API

dropdown.setData(items);
dropdown.setSelected(items);
dropdown.setSettings({ badgeShowLimit: 2 });
dropdown.setTheme("dark");
dropdown.getSelected();
dropdown.destroy();

Run Locally

Clone the repository and open the demo page:

git clone https://github.com/alexandroit/stackline-multiselect.git
cd stackline-multiselect
python3 -m http.server 4317

Then open:

http://127.0.0.1:4317/

License

MIT