Svelecte

Note

Svelte 5 compatible version available. More complete code update in progress.

npm i svelecte@next

Flexible autocomplete/select component written in Svelte. Initially inspired by Selectize.js. Also usable as custom element. Usable in forms, behaves very similar to standard <select> element.

See the latest changes on the Releases page.

📃 Features

searchable
multiselect with limit of max selected items
allow simple array or complex objects as items
custom item renderer (formatter)
allow creating new items (and possibly edit them)
remote data fetch
virtual list support
i18n and basic ARIA support
SSR support
client-validation support (tested with sveltekit-superforms)
lazy dropdown rendering
usable as custom element
customizable styling
dnd intergration with svelte-dnd-action

🔧 Installation

npm install svelecte --save

Minimalistic example

<script>
import Svelecte from 'svelecte';

const list = [{ id: 1, name: 'Item 1' }, { id: 2, name: 'Item 2'}, ...];
let myValue = null;
</script>

<Svelecte options={list} bind:value={myValue}></Svelecte>

Properties

Property	Type	Default	Description
name	`string`	`'svelecte'`	Create internal `<select>` element. Without `name` defined, no `<select>` is created
inputId	`string`	`null`	Allow targeting input using a html ID. Otherwise it is based on `name` property
required	`bool`	`false`	Make sense only when `name` is defined and you work with it as standard `<select>` element
disabled	`bool`	`false`	Disable component
options	`array`	`[]`	Option list, see Options for more info
optionResolver	`function`	`undefined`	Custom option resolver. Enabling "query mode". Check the example on Options page
value	`string`,`object`	`null`	Bound value property. For `multiple` is always array
valueAsObject	`bool`	`false`	Switch whether Svelecte should expects from and return to `bind:value` objects or primitive value (usually string, number)
parentValue	`string`	`undefined`	Value which this component depends on. When `parentValue` is `null`, component is disabled. There is an example on Remote Datasource page.
valueField	`string`	`null`	Property to be used as value (if not specified, will be resolved automatically)
labelField	`string`	`null`	Property shown in dropdown (if not specified, will be resolved automatically)
groupLabelField	`string`	`label`	Property to be used as optgroup label
groupItemsField	`string`	`options`	Property holding optgroup option list
disabledField	`string`	`$disabled`	Property to check, whether given options should be disabled and unselectable
placeholder	`string`	`Select`	Input placeholder
searchable	`bool`	`true`	Allow search among items by typing
clearable	`bool`	`false`	Display ✖ icon to clear whole selection
renderer	`mixed`	`null`	Dropdown and selection renderer function. More on Rendering page
disableHighlight	`bool`	`false`	Disable highlighting of input value in results. Can be useful with a `renderer` function that includes additional text or does its own highlighting
highlightFirstItem	`bool`	`true`	Automatically highlight the first item in the list when the dropdown opens
selectOnTab	`bool`,`string`	`null`	Based on value provided, it allows selecting currently active item by `Tab` AND (if value is `'select-navigate'`) also focus next input.
resetOnBlur	`bool`	`true`	Control if input value should be cleared on blur
resetOnSelect	`bool`	`true`	Control if input value should be cleared on item selection. Note: applicable only with `multiple`
closeAfterSelect	`bool`	`'auto'`	closes dropdown after selection. Setting this to `true` is useful for multiple select only. For single select dropdown is always closed no matter the value this property has
strictMode	`bool`	`true`	When `true`, passed value is checked whether exists on provided `options` array. If not, `invalidValue` event is dispatched
multiple	`bool`	`false`	allow multiselection. Will be set automatically to `true`, if `name` property ends with `[]`, like `tags[]`
max	`number`	`0`	Maximum allowed items selected, applicable only for multiselect
collapseSelection	`string`	`null`	Whether selection should be collapsed and when, check Rendering for more info.
keepSelectionInList	`bool`	`'auto'`	Whether keep selected items in dropdown. `auto` for `multiple` removes selected items from dropdown
creatable	`bool`	`false`	Allow creating new item(s)
creatablePrefix	`string`	`*`	Prefix marking new item
allowEditing	`bool`	`false`	When pressing `Backspace` switch to edit mode instead of removing newly created item. NOTE intended to be used with `creatable` property
keepCreated	`bool`	`true`	Switch whether to add newly created option to option list or not
delimiter	`string`	`,`	split inserted text when pasting to create multiple items
createFilter	`function`	`null`	Function, that transform input string to custom value. It can serve as a filter, if value is valid or not. If you want to dismiss entered value, function should return `''` (empty string). By default all input string is trimmed and all multiple spaces are removed.
createHandler	`function`	`null`	Custom (may be) async function transforming input string to option object. Default returns object with `valueField` and `labelField` properties, where `labelField`'s value is input string prefixed with `creatablePrefix` property.
fetch	`string`	`null`	Sets fetch URL. Visit [Remote datasource] form more details
fetchProps	`object`	`null`	Set options for new fetch Request
fetchCallback	`function`	`null`	optional fetch callback
fetchResetOnBlur	`bool`	`true`	reset previous search results on empty input, related to `resetOnBlur`
fetchDebounceTime	`number`	`300`	how many miliseconds is request debounced before fetch is executed
minQuery	`number`	`1`	Minimal amount of characters required to perform remote request. Usable with `fetch` property
lazyDropdown	`bool`	`true`	render dropdown after first focus, not by default
virtualList	`bool`	`false`	Whether use virtual list for dropdown items (useful for large datasets)
vlHeight	`number`	`null`	Height of virtual list dropdown (if not specified, computed automatically)
vlItemSize	`number`	`null`	Height of one row (if not specified, computed automatically)
searchProps	`object`	`null`	Customize `sifter.js` settings. See Searching page for more details
class	`string`	`svelecte-control`	default css class
i18n	`object`	`null`	I18n object overriding default settings
dndzone	`function`	noop	Pass `dndzone` from `svelte-dnd-action`, see Examples page
validatorAction	`array`	`null`	Bind validator action for inner `<select>` element. Designed to be used with `svelte-use-form`, see Validation page. For this to work, `name` property MUST be defined
anchor_element	`bool`	`null`	`internal`: when passing also existing select (for custom element)

Available slots

For more info refer to Rendering page.

<slot name="icon" />
<slot name="collapsedSelection" let:selectedOptions let:i18n />
<slot name="selection" let:selectedOptions let:bindItem />
<slot name="clear-icon" let:selectedOptions let:inputValue />
<slot name="dropdown-toggle" let:isOpen />
<slot name="list-header" />
<slot name="option" let:item />
<slot name="create-row" let:isCreating let:inputValue let:i18n  />

Emitted events:

Event	arguments	description
fetch	options	newly fetched remote options
fetchError	error	dispatche on fetch error of any kind
change	selection	selected objects. If `anchor` property is defined, `change` event is called also on it
createoption	option	newly created option object
createFail	object	thrown if `createHandler` fails
focus	`<input>`	focus event
blur	`<input>`	blur event
invalidValue	invalidValue	triggered when passed `value` is out of provided `options` items. Internal (and bound, if any) `value` is set to `null` or `[]` if multiple
enterKey	underlying `keyDown` event	triggered when natively it would cause form submit (dropdown is closed). This gives you ability to prevent it by calling `event.detail.preventDefault()`

Public API:

Name	type	arguments	description
focus	`function`	-	focus input
refetchWith	`function`	new value

There are global config and addRenderer function available. Refer to Global config and Rendering page respectively.

I18n, a11y, CSS variables

Visit documentation for more details.

Thanks to

selectize.js - main inspiration
sifter - search engine
svelte-tiny-virtual-list virtual list functionality
and svelte of course 😊

And if you want to thank me, you can through my sponsor page.

License

MIT License

mskocik/svelecte