LazySelect

Lightweight, dependency-free multi-select dropdown with server-side pagination, search, and selection persistence.

A lightweight multi-select dropdown for the case where you have thousands of options on the backend and need to load them on demand. Drop in one <script> tag and go.

<script src="https://cdn.jsdelivr.net/npm/@agentnova/lazyselect@1.0/lazyselect.min.js"></script>
<div id="categories"></div>
<script>
  new LazySelect('#categories', { url: '/api/categories' });
</script>

• ✅ Zero dependencies — no jQuery, no React, no Vue
• ✅ Server-side pagination via infinite scroll
• ✅ Debounced search
• ✅ Selections persist across search and pagination (the part homemade versions usually get wrong)
• ✅ Bring-your-own backend via responseAdapter
• ✅ Hidden input sync for plain HTML form submits — no JS config required
• ✅ One-line CDN install, styles included
• ✅ Bootstrap-friendly defaults, fully overridable CSS

---

Install

Via CDN (recommended)

<script src="https://cdn.jsdelivr.net/npm/@agentnova/lazyselect@1.0/lazyselect.min.js"></script>

Or unpkg:

<script src="https://unpkg.com/@agentnova/lazyselect@1/lazyselect.min.js"></script>

That's it. Styles inject themselves automatically. No CSS file to include.

Self-hosted

<script src="/static/lazyselect.min.js"></script>

npm

npm install @agentnova/lazyselect

import LazySelect from "@agentnova/lazyselect";

---

Quick start

<div id="my-filter"></div>

<script src="https://cdn.jsdelivr.net/npm/@agentnova/lazyselect@1.0/lazyselect.min.js"></script>
<script>
  const ms = new LazySelect('#my-filter', {
    url: '/api/categories',
    placeholder: 'Search categories...',
    onChange: (ids, items) => console.log(ids, items)
  });
</script>

Your endpoint should accept ?page=1&pageSize=10&search=foo and return:

{ "items": [{ "id": 1, "name": "Foo" }, { "id": 2, "name": "Bar" }] }

That's the whole contract. Send back items, get back a working multi-select.

---

Backend example

# Django
def load_filter_data(request):
    page = int(request.GET.get('page', 1))
    page_size = int(request.GET.get('pageSize', 10))
    search = request.GET.get('search', '')

    qs = MyModel.objects.filter(name__icontains=search)
    start = (page - 1) * page_size
    items = qs[start:start + page_size].values('id', 'name')
    return JsonResponse({'items': list(items)})

// Express / Node
app.get('/api/categories', async (req, res) => {
  const { page = 1, pageSize = 10, search = '' } = req.query;
  const offset = (page - 1) * pageSize;
  const items = await db.query(
    'SELECT id, name FROM categories WHERE name LIKE ? LIMIT ? OFFSET ?',
    [`%${search}%`, +pageSize, offset]
  );
  res.json({ items });
});

If your endpoint returns a different shape, use responseAdapter:

new LazySelect('#x', {
  url: '/api/users',
  responseAdapter: (raw) => ({
    items: raw.results.map(u => ({ id: u.uuid, name: u.full_name }))
  })
});

---

Options

Option	Type	Default	Description
url	string	required	Endpoint that returns paginated items.
containerKey	string	''	Sent to the server as container_data. Useful when one endpoint serves multiple dropdowns.
pageSize	number	10	Items per request.
searchDebounce	number	300	Milliseconds to wait after typing before searching.
placeholder	string	'Search...'	Input placeholder.
selectedTextFn	fn(n)	'N items selected'	Text shown when items are selected.
noDataText	string	'No data available'	Empty-state message.
loadingText	string	'Loading...'	Loading-state message.
errorText	string	'Failed to load'	Error-state message.
method	string	'GET'	HTTP method. Use 'POST' to send body as JSON.
extraParams	object	{}	Static params merged into every request.
getExtraParams	fn()	null	Returns dynamic params (e.g. dependent dropdown values).
headers	object	{}	Custom request headers (CSRF, auth, etc).
responseAdapter	fn(raw)	passthrough	Transform server response into {items, total}.
resolveNames	fn(ids)	null	Returns Promise<[{id,name}]> to label pre-selected ids.
onChange	fn(values, items)	null	Fires on every selection change.
onReady	fn(instance)	null	Fires after first load.
onError	fn(error)	null	Fires on network/parse errors.
initialValues	array	[]	Pre-select. Pass [1,2,3] or [{id:1,name:'Foo'}].
closeOnSelect	bool	false	Close dropdown after each pick.
maxHeight	string	'240px'	Dropdown panel height.
autoInjectStyles	bool	true	Set false to use your own CSS.
hiddenInputName	string	null	Auto-create <input type="hidden" name="..."> synced with selections.
hiddenInputSelector	string	null	Sync to an existing hidden input instead.
hiddenInputJoin	string	','	',' (CSV), 'json', or any separator.

---

API methods

ms.getValues();              // ['1', '5', '7']
ms.getSelected();            // [{id:'1', name:'Foo'}, ...]
ms.setValues([1, 2, 3]);     // pre-select by id
ms.setValues([{id:1, name:'Foo'}, ...]);  // or with names (skips resolveNames)
ms.clear();                  // unselect all
ms.reload();                 // reset search and reload
ms.open();
ms.close();
ms.destroy();                // teardown, remove DOM, abort pending requests

Static helpers

// Auto-init by data attributes (no JS config needed)
LazySelect.autoInit();

// Override defaults globally
LazySelect.setDefaults({ pageSize: 25, searchDebounce: 200 });

---

Recipes

Sync to a hidden input for plain form submission

<form action="/search" method="get">
  <div id="cat" data-ls-url="/api/categories" data-ls-name="categories"></div>
  <button>Search</button>
</form>
<script>LazySelect.autoInit();</script>

The form will submit ?categories=1,5,7 automatically — zero JavaScript config.

Send CSRF tokens (Django, Rails, etc)

new LazySelect('#x', {
  url: '/api/items',
  method: 'POST',
  headers: { 'X-CSRFToken': getCookie('csrftoken') }
});

Pre-select with names already known

new LazySelect('#x', {
  url: '/api/items',
  initialValues: [{id: 5, name: 'Engineering'}, {id: 12, name: 'Sales'}]
});

Pre-select by id only, fetch names lazily

new LazySelect('#x', {
  url: '/api/items',
  initialValues: [5, 12],
  resolveNames: (ids) => fetch('/api/items/lookup?ids=' + ids.join(','))
                            .then(r => r.json())
});

Dependent dropdowns

const country = new LazySelect('#country', {
  url: '/api/countries',
  onChange: () => city.reload()
});
const city = new LazySelect('#city', {
  url: '/api/cities',
  getExtraParams: () => ({ country: country.getValues().join(',') })
});

Auto-init from HTML (no JS config)

<div data-ls-url="/api/categories" data-ls-key="cat"
     data-ls-placeholder="Pick categories" data-ls-name="cat_ids"></div>
<div data-ls-url="/api/users" data-ls-key="usr" data-ls-page-size="20"></div>

<script>LazySelect.autoInit();</script>

Custom styling

Either set autoInjectStyles: false and write your own CSS using the same class names, or just override what you need:

.ls-dropdown { border-color: #6610f2; }
.ls-item:hover { background: #e7f1ff; }
.ls-search:focus { border-color: #6610f2; box-shadow: 0 0 0 .2rem rgba(102,16,242,.15); }

CSS class names: .ls-container, .ls-search, .ls-dropdown, .ls-items, .ls-item, .ls-loading, .ls-empty, .ls-error.

---

How is this different from select2 / choices.js / chosen?

Those are excellent libraries, but they all expect the full options list to be available client-side, or use ad-hoc AJAX patterns layered on top. LazySelect is built around server-side pagination from the start: every option you see came from a paged API request, search runs server-side, and selections persist correctly even when the user has only ever seen a fraction of the available items.

If your data fits in the page, use <select multiple> or one of the libraries above. If you have thousands of rows, use this.

---

Browser support

Modern evergreen browsers. Uses fetch, Promise, AbortController, Object.assign, and dataset — IE11 is not supported.

Size

File	Size
lazyselect.js	~18 KB
lazyselect.min.js	~11 KB
Minified + gzipped	~3.7 KB

Contributing

Bug reports and pull requests are welcome at github.com/agentnova/lazyselect. For substantial changes, please open an issue first to discuss.

License

MIT © agentnova