Flexible autocomplete/select component written in Svelte. Massively inspired by Selectize.js. Also usable as custom element (CE). Usable in forms, behaves very similar to standard <select>
element.
See the latest changes on the Releases page.
- 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 support
- SSR support
- lazy dropdown rendering
- usable as custom element
- stylable
- reordable multi selection with addition of
svelte-dnd-action
(example) - usable with
svelte-use-form
(example)
npm install svelecte --save
<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>
💭 Note about value
and readSelection
property
myValue = 2;
This would select item with id
property 2
.
Sometimes you want to work strictly with objects, like myValue = {id: 2, name: 'Item 2'}
. You can set property valueAsObject
which tells Svelecte to handle value
property as object or array of object (if multiple
is also set).
Property readSelection
always returns selected object or object array no matter if valueAsObject
is set or not.
👉 Examples with more detailed documentation can be found at https://mskocik.github.io/svelecte/.
Property | Type | Default | Description |
---|---|---|---|
options | array | [] |
Data array |
valueAsObject | bool | false |
Switch whether Svelecte should expects from and return to bind:value objects or primitive value (usually string, number) |
valueField | string | null |
Property to be used as value (if not specified, will be selected automatically) |
labelField | string | null |
Property shown in dropdown (if not specified, will be selected automatically) |
disabledField | string | $disabled |
Property to check, whether given options should be disabled and unselectable |
required | bool | false |
make sense only when name is defined |
placeholder | string | Select |
Input placeholder |
searchable | bool | true |
Allow search among items by typing |
disabled | bool | false |
Disable component |
renderer | string|function | null |
dropdown and selection renderer function. More info in item rendering section |
controlItem | Component | Item |
Item component when item is selected. See Custom Items section for more details. |
dropdownItem | Component | Item |
Item component in dropdown. See Custom Items section for more details. |
selectOnTab | bool | false |
Allow selecting currently active item by Tab key |
resetOnBlur | bool | true |
Control if input value should be cleared on blur |
clearable | bool | false |
Display ✖ icon to clear whole selection |
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 | bool | false |
collapse selection when multiple and not focused |
name | string | null |
create <select> , usable for normal forms. |
inputId | string | null |
allow targeting input using a html label. |
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 |
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 |
fetch | string|function | null |
Check "remote datasource" section for more details |
fetchMode | string | auto |
When set to init options are fetched only when mounted, when searching it search in downloaded dataset |
fetchCallback | function | null |
optional fetch callback |
fetchResetOnBlur | bool | true |
reset previous search results on empty input, related to resetOnBlur |
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) |
searchField | string|array | null |
Specify item property that will be used to search by (if not specified all props except value prop will be used) |
sortField | string | null |
Specify sort property. If not specified, labelField will be used |
disableSifter | bool | false |
Disable Sifter filtering & sorting. Can be useful in combination with fetch , when further filtering or sorting may be undesired |
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 |
class | string | svelecte-control |
default css class |
style | string | null |
inline style |
hasAnchor | bool | null |
internal : when passing also existing select (for CE) |
i18n | object | null |
I18n object overriding default settings |
dndzone | function | empty | Pass dndzone from svelte-dnd-action , if you want to support selection reordering. See the example REPL |
validatorAction | array | null |
Bind validator action for inner <select> element. Designed to be used with svelte-use-form . See the example REPL |
If renderer
property is not enough for you or you prefer Component syntax to HTML strings, you can use your own Components. Keep in mind that default Item
component handles highlighting when searching, but the rest of features
like styling should be inherited if you use proper css classes (the same as Item
component)..
To make it easier to use your own Components, there are available actions, highlighting function and close button icon for you to use.
The simplest example can be found in this REPL.
Event | arguments | description |
---|---|---|
fetch | options | newly fetched remote options |
change | selection | selected objects. If anchor property is defined, change event is called also on it |
createoption | option | newly created option object |
blur | - | blur event |
Name | type | arguments | description |
---|---|---|---|
focus | function | - | focus input |
getSelection | function | bool | return selection, if true is passed, only values are returns, whole objects otherwise |
setSelection | function | array | set selection programmatically |
config | property | - | context property: global common config for all instances, you can override most properties here and also some additional, mainly i18n |
addFormatter | function | - | context function: with signature (name, formatFn) you can add additional item renderers (formatters) |
This is default value of i18n
property:
// config.i18n defaults:
{
i18n: {
empty: 'No options',
nomatch: 'No matching options',
max: num => `Maximum items ${num} selected`,
fetchBefore: 'Type to start searching',
fetchQuery: (minQuery, inputLength) => `Type ${minQuery > 1 && minQuery > inputLength
? `at least ${minQuery - inputLength} characters `
: '' }to start searching`,
fetchEmpty: 'No data related to your search',
collapsedSelection: count => `${count} selected`,
createRowLabel: value => `Create '${value}'`
},
collapseSelectionFn: function(selectionCount, selection) {
return settings.i18n.collapsedSelection(selectionCount);
}
}
You can override whole object or only items you are interested in. You can override it globally or on component level:
// global override
import Svelecte, { config } from 'svelecte';
config.i18n = {
empty: '🚫',
nomatch: '✋',
max: num => '🙄',
fetchBefore: '💻',
fetchQuery: (minQuery, inputLength) => '🧮',
fetchEmpty: '🚮',
collapsedSelection: () => '🗃',
createRowLabel: value => `📝 ${value}`
}
// local override (component-level)
const myI18n = {
empty: `Empty list, can't you see?`
}
<Svelecte i18n={myI18n}></Svelecte>
- selectize.js - inspiration
- sifter - search engine
- svelte-select - inspiration & how-to, including some code borrowing 😊
- svelte-tiny-virtual-list virtual list capability