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

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

License

MIT License

Top categories

svelte logo

Need a Svelte website built?

Hire a professional Svelte developer today.
Loading Svelte Themes