<dw-select> / <dw-multi-select>

A mobile-first, single and multiple select / auto-complete solution in Material Design style, built with LitElement. Supports grouping, virtualization for large lists, keyboard navigation, form validation, and adaptive dialog types (popover, modal, fit, bottom-sheet).

---

1. User Guide

Installation & Setup

npm install @dreamworld/dw-select

// Single select
import '@dreamworld/dw-select';

// Multi-select
import '@dreamworld/dw-multi-select';

---

Basic Usage

Single Select (Default)

<dw-select
  label="Country"
  .items="${this.items}"
  valueExpression="_id"
  .valueTextProvider="${(item) => item.name}"
></dw-select>

Single Select (Outlined, Pre-selected)

<dw-select
  outlined
  label="Country"
  .items="${this.items}"
  .value="${this.selectedItem}"
  .valueProvider="${(item) => item.id}"
  .valueTextProvider="${(item) => item.name}"
></dw-select>

Single Select (Searchable)

<dw-select
  outlined
  searchable
  label="Bank"
  .items="${this.items}"
  .valueTextProvider="${(item) => item.name}"
></dw-select>

Multi-Select

<dw-multi-select
  outlined
  label="Tags"
  .items="${this.items}"
  .value="${this.selectedValues}"
  .valueTextProvider="${(item) => item.label}"
  @change="${(e) => this.selectedValues = e.target.value}"
></dw-multi-select>

---

API Reference — <dw-select>

Properties / Attributes

Name	Type	Default	Description
name	string	""	Sets the name attribute on the internal input. Used for browser autofill only.
value	object	null	The currently selected item object. Set programmatically to change selection.
originalValue	object	undefined	When specified and different from value (by reference), a highlight is shown. Requires highlightChanged=true.
highlightChanged	boolean	false	When true, highlights the field when value !== originalValue (by reference).
outlined	boolean	false	Shows the outlined Material variant.
label	string	""	Floating label text.
placeholder	string	""	Disappearing input placeholder.
helper	string	""	Helper text displayed below the input (visible on focus by default).
helperPersistent	boolean	false	Always shows helper text regardless of focus state.
readOnly	boolean	false	Read-only display state. Reflects as read-only attribute.
required	boolean	false	Applies required validation; shows error on blur if empty.
error	string | Function	undefined	Custom error message. Can be a string or a function returning a string.
errorMessages	object	undefined	Error state messages object.
autoValidate	boolean	false	Reports validity on value change rather than only on blur.
disabled	boolean	false	Disables the component.
searchable	boolean	false	Enables search/filter input in the dialog.
extraSearchFields	string[]	undefined	Additional item fields to include in search filtering.
groups	Group[]	null	List of group definitions for grouping items.
groupSelector	Function	undefined	(item) => groupName. Identifies the group of an item. Takes precedence over groupExpression.
groupExpression	string	""	Dot-separated property path on item to find its group name. Ignored if groupSelector is set.
items	object[]	undefined	Array of selectable items. When undefined, shows a loading state.
prependItems	object[]	[]	Items always shown at the top of the list (e.g., "All", "None").
valueProvider	Function	undefined	(item) => value. Extracts the value from an item. Takes precedence over valueExpression.
valueExpression	string	"_id"	Dot-separated property path on item to extract its value. Used when valueProvider is not set.
valueTextProvider	Function	(item) => item	(item) => string. Returns the display text for an item.
valueEquator	Function	(v1, v2) => v1 === v2	Custom equality check for value comparison.
dialogWidth	number	undefined	Override width (px) for popover and fit dialogs. Bottom-sheet is always full-width.
renderItem	Function	undefined	(item, selected, activated, query) => HTMLTemplate. Custom item template. Must not be focusable.
renderGroupItem	Function	undefined	(name, label, collapsible, collapsed, activated) => HTMLTemplate. Custom group item template.
heading	string	""	Heading shown on the bottom-sheet dialog.
showClose	boolean	false	Shows a close icon-button in the top-right corner of the bottom-sheet dialog.
selectedTrailingIcon	string	undefined	Material icon name shown as trailing icon on the selected item in the list.
messages	Messages	See Messages	Override dialog state messages.
searchPlaceholder	string	""	Placeholder for the fit dialog's search input.
helperTextProvider	Function	undefined	(item) => string. Provides helper text based on the selected item. Overrides helper when set.
queryFilter	Function	undefined	(item, query) => boolean. Custom search filter function.
highlightQuery	boolean	true	When false, disables highlighting of matched words in the list.
allowNewValue	boolean	false	Allows creating a new value from the search query. Only works when searchable=true.
newItemProvider	Function	undefined	(query) => {item, hint} | Promise. Builds a new item from the typed query. Return undefined or {item: undefined} when query is incomplete.
newItems	object	undefined	Hash of item IDs to treat as new: {id1: true, id2: true}. Works independently of allowNewValue.
warning	string	undefined	Warning message text.
dense	boolean	false	Uses dense styling on the trigger element.
popover	boolean	false	Forces the popover dialog type.
popoverStyles	object	undefined	External styles applied to the popover dialog.
autoComplete	boolean	false	Enables auto-complete mode.
readOnlyTrigger	boolean	false	Shows read-only mode with a trigger icon instead of an input.
highlightedValue	boolean	false	When true, shows the value in highlighted (headline6) style. Reflects as highlighted-value.
interactiveDialog	boolean	false	Makes the dialog interactive (delegates pointer events).
iconButtonSize	number	undefined	Size (px) for the trailing icon button in the trigger.
hintInTooltip	boolean	false	Shows hint text in a tooltip triggered by an info icon.
errorInTooltip	boolean	false	Shows error text in a tooltip triggered by an error icon.
warningInTooltip	boolean	false	Shows warning text in a tooltip triggered by a warning icon.
hintTooltipActions	Action[]	undefined	Actions shown inside the hint tooltip. Dispatches action event on click.
errorTooltipActions	Action[]	undefined	Actions shown inside the error tooltip.
warningTooltipActions	Action[]	undefined	Actions shown inside the warning tooltip.
tipPlacement	string	""	Tooltip placement. See Tippy.js placement docs.

Methods

Name	Signature	Returns	Description
checkValidity	checkValidity()	boolean	Returns true if valid; fires valid event. Returns false and fires invalid event otherwise.
reportValidity	reportValidity()	boolean	Runs checkValidity() and reports validation state to the user.
validate	validate()	boolean	Validates input. Returns false if value is invalid.
focus	focus()	void	Focuses the trigger element.

Getter:

Name	Returns	Description
item	object	The full item object corresponding to the current value.

Events

Event	Detail	Description
change	none	Fired when the user changes selection. Not fired when the same value is re-selected.
selected	none	Deprecated. Use change instead.
valid	ValidityState	Fired when checkValidity() passes.
invalid	ValidityState	Fired when checkValidity() fails (also on blur).
clear-selection	none	Fired when the user explicitly clears the selection by removing all input text (searchable only).
dw-dialog-opened	none	Fired when the dropdown dialog opens.
dw-dialog-closed	none	Fired when the dropdown dialog closes.

CSS Custom Properties

Property	Default	Description
--dw-select-item-selected-bg-color	#6200ee	Background color of the selected item in the list.
--dw-select-selected-item-bg-opacity	0	Opacity of the selected item background.
--dw-select-highlight-bg-color	#fde293	Background color for query-match highlights.
--dw-select-highlight-text-color	—	Text color for query-match highlights.
--dw-select-highlight-font-weight	—	Font weight for query-match highlights.
--dw-select-shimmer-gradient	linear-gradient(to right, #f1efef, #f9f8f8, #e7e5e5)	Shimmer gradient shown while items is loading.
--dw-select-content-padding	—	Padding inside the dialog content area.
--dw-select-read-only-trigger-value-color	—	Text color for the value in readOnlyTrigger mode.
--dw-select-trigger-label-padding	0px 38px 0px 0px	Padding of the trigger's label.
--dw-select-trigger-trailing-icon-margin-right	4px	Right margin of the trailing icon in the trigger.
--dw-popover-min-width	0px	Minimum width of the popover dialog.
--modal-dialog-header-max-height	56px	Maximum height of the modal dialog header.
--mdc-theme-primary	#6200ee	Primary color (used for selected item, focus ring).
--mdc-theme-error	#b00020	Error color.

---

API Reference — <dw-multi-select>

Properties / Attributes

Name	Type	Default	Description
name	string	""	Sets the name attribute on the internal input.
value	object[]	[]	Array of selected item values.
outlined	boolean	false	Shows the outlined Material variant.
label	string	""	Floating label text.
placeholder	string	""	Disappearing input placeholder.
error	string | Function	undefined	Custom error message.
errorMessages	object	undefined	Error state messages object.
autoValidate	boolean	false	Reports validity on value change rather than only on blur.
disabled	boolean	false	Disables the component.
searchable	boolean	false	Enables search/filter input in the dialog. Shown automatically when items > 10.
extraSearchFields	string[]	undefined	Additional item fields to include in search filtering.
groups	Group[]	null	List of group definitions.
groupSelector	Function	undefined	(item) => groupName. Takes precedence over groupExpression.
groupExpression	string	""	Dot-separated property path to find item's group.
items	object[]	undefined	Array of selectable items.
valueProvider	Function	undefined	(item) => value. Extracts value from an item.
valueExpression	string	"_id"	Dot-separated path to extract item value.
valueTextProvider	Function	(item) => item	(item) => string. Returns display text for an item.
valueEquator	Function	(v1, v2) => v1 === v2	Custom equality check for value comparison.
dialogWidth	number	undefined	Override width (px) for popover and fit dialogs.
renderItem	Function	undefined	(item, selected, activated, query) => HTMLTemplate. Custom item template.
renderGroupItem	Function	undefined	(name, label, collapsible, collapsed, activated) => HTMLTemplate. Custom group item template.
heading	string	""	Heading shown on the bottom-sheet dialog.
showClose	boolean	false	Shows a close icon-button on the bottom-sheet dialog.
selectedTrailingIcon	string	undefined	Material icon name on selected item in the list.
messages	Messages	See Messages (multi)	Override dialog state messages.
queryFilter	Function	undefined	(item, query) => boolean. Custom search filter.
highlightQuery	boolean	true	When false, disables match highlighting.
warning	string	undefined	Warning message text.
dense	boolean	false	Uses dense styling on the trigger element.
popover	boolean	false	Forces the popover dialog type.
popoverStyles	object	undefined	External styles applied to the popover dialog.
hasItemLeadingIcon	boolean	false	When true, moves the checkbox to the right side of items (leading icon is on the left).
iconButtonSize	number	undefined	Size (px) for the trailing icon button in the trigger.

Events

Event	Detail	Description
change	none	Fired when the applied selection changes.
dw-multi-select-opened	none	Fired when the dropdown dialog opens.
dw-multi-select-closed	none	Fired when the dropdown dialog closes.

CSS Custom Properties

Inherits all CSS custom properties from <dw-select>, plus:

Property	Default	Description
--dw-multi-select-trigger-trailing-icon-margin-right	4px	Right margin of the trailing icon in the multi-select trigger.

---

Type Reference

Group

Key	Type	Required	Description
name	string	Yes	Unique identifier for the group.
title	string	Yes	Display name shown as the group header.
collapsible	boolean	Yes	Whether the group can be collapsed by the user.
collapsed	boolean	Yes	Initial collapse state.
icon	string	No	Material icon name shown alongside the group title.

// Example
const group = {
  name: 'BANKS',
  title: 'Banks',
  collapsible: true,
  collapsed: false,
  icon: 'account_balance'
};

Action

Key	Type	Description
name	string	Action identifier (available in the action event).
label	string	Display label for the action button.
danger	boolean	When true, renders the action in a danger/red style.

Messages (single select) {#messages}

Key	Type	Default	Description
noRecords	string	"No Records"	Shown when items is an empty array.
noMatching	string	"No matching records found!"	Shown when the search query yields no results.
loading	string	"Loading..."	Shown when items is undefined.

Messages (multi-select) {#messages-multi}

Same keys as single-select, plus:

Key	Type	Default	Description
selectAll	string	"Select All"	Label for the Select All option.
searchPlaceholder	string	"Search..."	Placeholder for the search input inside the dialog.

ValueProvider and ValueExpression

• If neither is provided, the entire item object is used as the value.
• If only valueExpression is provided, the value is extracted from that dot-separated path.
• If only valueProvider is provided, the function is called with the item.
• If both are provided, valueExpression takes precedence and valueProvider is ignored.

---

Configuration Options

These constants are defined internally in dw-select-base-dialog.js and dw-multi-select-base-dialog.js and control virtualization and scroll behavior:

Constant	Value	Description
VIRTUAL_LIST_MIN_LENGTH	500	Item count threshold above which @lit-labs/virtualizer is enabled.
VIRTUAL_LIST_AUTO_SCROLL_DELAY	500 ms	Delay before auto-scrolling to the selected item when the virtualizer is active.
REGULAR_LIST_SCROLL_DELAY	300 ms	Delay before auto-scrolling to the selected item in a regular (non-virtualized) list.

---

Advanced Usage

Groups with Collapsible Sections

// In your LitElement component
get groups() {
  return [
    { name: 'PUBLIC', title: 'Public Banks', collapsible: true, collapsed: false },
    { name: 'PRIVATE', title: 'Private Banks', collapsible: true, collapsed: true }
  ];
}

get items() {
  return [
    { _id: 1, name: 'SBI', group: 'PUBLIC' },
    { _id: 2, name: 'HDFC', group: 'PRIVATE' }
  ];
}

<dw-select
  .groups="${this.groups}"
  .items="${this.items}"
  groupExpression="group"
  .valueTextProvider="${(item) => item.name}"
></dw-select>

Allow New Value (Searchable Only)

When allowNewValue=true and the query does not match any item, a new item can be created via newItemProvider.

<dw-select
  searchable
  allowNewValue
  .items="${this.items}"
  .newItemProvider="${this._newItemProvider}"
  .valueTextProvider="${(item) => item.name}"
></dw-select>

// newItemProvider: returns {item, hint} or undefined, or a Promise resolving to either
_newItemProvider(query) {
  if (query.length < 2) return undefined;
  return { item: { _id: query, name: query }, hint: 'Press Enter to add' };
}

The newItemProvider function receives the current search query and must return:

• {item: Item, hint: string} — a new item and optional hint text shown on the input
• undefined or {item: undefined} — when the query is not yet complete
• A Promise resolving to either of the above

Custom Item Rendering

// renderItem: (item, selected, activated, query) => HTMLTemplate
renderItem(item, selected, activated, query) {
  return html`
    <dw-list-item
      .selected="${selected}"
      .activated="${activated}"
      title1="${item.name}"
      title2="${item.code}"
    ></dw-list-item>
  `;
}

<dw-select .renderItem="${this.renderItem}"></dw-select>

Custom Search Filter

import { queryFilterGenerator } from '@dreamworld/dw-select/utils.js';

// Search across multiple fields
const filter = queryFilterGenerator(['name', 'code', 'alias']);

// Or provide a fully custom filter
const customFilter = (item, query) => item.name.toLowerCase().startsWith(query.toLowerCase());

<dw-select searchable .queryFilter="${filter}"></dw-select>

Prepend Items

get prependItems() {
  return [{ _id: null, name: '— None —' }];
}

<dw-select .prependItems="${this.prependItems}" .items="${this.items}"></dw-select>

Tooltip Variants

<!-- Show helper text in tooltip on info icon -->
<dw-select
  hintInTooltip
  helper="Start typing to filter results"
></dw-select>

<!-- Show error in tooltip with an action -->
<dw-select
  errorInTooltip
  .errorTooltipActions="${[{ name: 'fix', label: 'Fix Now', danger: false }]}"
  @action="${(e) => console.log(e.detail.name)}"
></dw-select>

Form Validation Integration

// Programmatic validation
const select = document.querySelector('dw-select');

// Check validity without showing UI
const isValid = select.checkValidity();

// Check validity and show error to user
const isValid = select.reportValidity();

// Custom validate call
const isValid = select.validate();

<dw-select required autoValidate label="Required Field"></dw-select>

---

2. Developer Guide / Architecture

Architecture Overview

<dw-select>                          <dw-multi-select>
├── DwFormElement(LitElement) mixin  ├── DwFormElement(LitElement) mixin
├── <dw-select-trigger>              ├── <dw-multi-select-trigger>
│   └── extends DwInput              │   └── extends DwInput
└── <dw-select-base-dialog>          └── <dw-multi-select-base-dialog>
    ├── extends DwCompositeDialog        ├── extends DwCompositeDialog
    ├── <dw-select-dialog-input>         ├── <dw-multi-select-dialog-input>
    ├── <dw-select-group-item>           └── <dw-multi-select-group-item>
    └── @lit-labs/virtualizer

Design Patterns

Pattern	Implementation
Mixin	DwFormElement(LitElement) injects standard form validation API (checkValidity, reportValidity, validate, name) into both components.
Composite / Delegation	Each select component is split into a trigger (display) and a dialog (selection logic). The orchestrator (dw-select.js) coordinates state between the two.
Observer (Reactive Properties)	LitElement's @property decorator pattern drives all UI updates declaratively.
Strategy	valueProvider, queryFilter, renderItem, and renderGroupItem are pluggable function properties, allowing integrators to override behavior without subclassing.
Virtualizer	@lit-labs/virtualizer is activated automatically when the rendered item count exceeds VIRTUAL_LIST_MIN_LENGTH (500), ensuring smooth performance with large datasets.
Responsive / Adaptive	@dreamworld/device-info provides the current layout (small, medium, large, hd, fullhd). The dialog type is chosen accordingly — bottom-sheet on mobile, popover/fit on desktop.

Module Responsibilities

Module	Responsibility
dw-select.js	Orchestrator for single select. Manages validation, layout detection, value resolution, and delegates rendering to trigger + dialog.
dw-multi-select.js	Orchestrator for multi-select. Adds array-value management, "Select All" logic, and apply/cancel flow.
dw-select-trigger.js	The visible input field. Extends DwInput. Renders the trailing expand/clear icon and dispatches expand-toggle and clear-selection events.
dw-multi-select-trigger.js	Same as above for multi-select. Extends DwInput.
dw-select-base-dialog.js	Dialog for single select. Handles item filtering, keyboard navigation, group collapse, highlight, virtualization, and scroll-to-selected.
dw-multi-select-base-dialog.js	Dialog for multi-select. Adds checkbox toggle, "Select All" when ≥10 items, and an apply/done button.
dw-select-dialog-input.js	Search input component rendered inside the single-select dialog. Dispatches input-change, cancel, and clear-selection.
dw-multi-select-dialog-input.js	Search input for the multi-select dialog.
dw-select-group-item.js	Renders collapsible group header rows. Shows expand/collapse icon and ripple only when collapsible=true.
dw-multi-select-group-item.js	Renders non-collapsible group header rows for multi-select.
utils.js	Exports KeyCode, Direction, Position, NEW_VALUE_STATUS, filter(), and queryFilterGenerator().
sort-items.js	Exports sortItems(). Scores items by relevance to the query (prefix match, word match, exact word match) and returns them sorted.

Dialog Types & Adaptive Layout

The dialog type is selected automatically based on device layout and item count:

Dialog Type	When Used
popover	Default on desktop. Anchored to the trigger element.
fit	Full-height dialog with integrated search input. Used when item list overflows.
modal	Centered modal overlay.
bottom-sheet	On mobile (small layout / virtual keyboard present).

The popover property on both components can force popover mode regardless of layout.

Utility Functions

filter(value, query) — utils.js

import { filter } from '@dreamworld/dw-select/utils.js';
filter('HDFC Bank', 'hdfc bank'); // true
filter('State Bank of India', 'bank india'); // true
filter('HDFC Bank', 'icici'); // false

Returns true if every word in query appears (as a substring) in at least one word of value. Case-insensitive.

queryFilterGenerator(keys) — utils.js

import { queryFilterGenerator } from '@dreamworld/dw-select/utils.js';

const filter = queryFilterGenerator(['name', 'shortCode', 'alias']);
// Returns: (item, query) => boolean

Generates a filter function that concatenates the specified keys from an item and runs filter() against the query.

sortItems(items, valueTextProvider, extraSearchFields, query) — sort-items.js

import { sortItems } from '@dreamworld/dw-select/sort-items.js';

const sorted = sortItems(items, (item) => item.name, ['code'], 'hdfc');

Sorts items by relevance to query. Scoring (lower = better):

• -1 if item text starts with the query
• -1 for each query word found anywhere in item text
• -1 for each exact word match

NEW_VALUE_STATUS — utils.js

import { NEW_VALUE_STATUS } from '@dreamworld/dw-select/utils.js';

// NEW_VALUE_STATUS.IN_PROGRESS — item is being created (spinner shown)
// NEW_VALUE_STATUS.NEW_VALUE   — item was created (shows "new" tag)
// NEW_VALUE_STATUS.ERROR       — creation failed (error shown)

Dependencies

Package	Purpose
@dreamworld/device-info	Detects device layout for adaptive dialog selection
@dreamworld/dw-button	Button component used in dialog footers
@dreamworld/dw-dialog	Base composite dialog implementation
@dreamworld/dw-form	DwFormElement mixin for form participation
@dreamworld/dw-icon	Icon rendering
@dreamworld/dw-icon-button	Trailing icon buttons in triggers
@dreamworld/dw-input	Base input element extended by triggers
@dreamworld/dw-list-item	Default item renderer inside dialogs
@dreamworld/dw-ripple	Ripple interaction effect
@dreamworld/dw-tooltip	Hint / error / warning tooltips
@dreamworld/material-styles	Material typography and theme tokens
@lit-labs/virtualizer	Virtual scroll for large item lists
@material/mwc-circular-progress	Loading spinner
lodash-es	Utility functions (find, debounce, isEmpty, sortBy, etc.)