svelte-select
A select/autocomplete component for Svelte apps. With support for grouping, filtering, async and more.
Demos
๐ฑโSimple demo
๐ปโAdvanced demo
Installation
yarn add svelte-select
Note: Install as a dev dependency (yarn add svelte-select --dev) if using Sapper to avoid a SSR error.
Usage
<script>
import Select from 'svelte-select';
let items = [
{value: 'chocolate', label: 'Chocolate'},
{value: 'pizza', label: 'Pizza'},
{value: 'cake', label: 'Cake'},
{value: 'chips', label: 'Chips'},
{value: 'ice-cream', label: 'Ice Cream'},
];
let selectedValue = undefined;
</script>
<Select {items} bind:selectedValue></Select>
API
-
items: Array
Default:[]
. List of selectable items that appear in the dropdown. -
selectedValue: Any
Default:undefined
. Selected item or items -
filterText: String
Default:''
. Text to filteritems
by. -
placeholder: String
Default:'Select...'
. Placeholder text. -
noOptionsMessage: String
Default:'No options'
. Message to display in list when there are noitems
. -
optionIdentifier: String
Default:'value'
. Override default identifier. -
listOpen: Boolean
Default:false
. Open/close list. -
hideEmptyState: Boolean
Default:false
. Hide list and don't shownoOptionsMessage
when there are noitems
. -
containerClasses: String
Default:''
. Add extra container classes, for example 'global-x local-y'. -
containerStyles: String
Default:''
. Add inline styles to container. -
isClearable: Boolean
Default:true
. Enable clearing of selected items. -
isCreatable: Boolean
Default:false
. Can create new item(s) to be added toselectedValue
. -
isDisabled: Boolean
Default:false
. Disable select. -
isMulti: Boolean
Default:false
. Enable multi-select,selectedValue
becomes an array of selected items. -
isSearchable: Boolean
Default:true
. Enable search/filtering ofitems
viafilterText
. -
isGroupHeaderSelectable: Boolean
Default:false
. Enable selectable group headers initems
(see adv demo). -
listPlacement: String
Default:'auto'
. When'auto'
displays either'top'
or'bottom'
depending on viewport. -
hasError: Boolean
Default:false
. Show/hide error styles around select input (red border by default). -
listAutoWidth: Boolean
Default:true
. List width will grow wider than the Select container (depending on list item content length). -
showIndicator: Boolean
Default:false
. If true, the chevron indicator is always shown. -
inputAttributes: Object
Default:{}
. Useful for passing in HTML attributes like'id'
to the Select input. -
Item: Component
Default:Item
. Item component. -
Selection: Component
Default:Selection
. Selection component. -
MultiSelection: Component
Default:MultiSelection
. Multi selection component. -
Icon: Component
Default:Icon
. Icon component. -
iconProps: Object
Default:{}
. Icon props. -
indicatorSvg: @html
Default:undefined
. Override default SVG chevron indicator. -
isVirtualList: Boolean
Default:false
. Uses svelte-virtual-list to render list (experimental).
Exposed methods
If you really want to get your hands dirty these internal functions are exposed as props to override if needed. See the adv demo or look through the test file (test/src/index.js) for examples.
export let itemFilter = (label, filterText, option) => label.toLowerCase().includes(filterText.toLowerCase());
export let groupBy = undefined; // see adv demo for example
export let groupFilter = groups => groups;
export let createGroupHeaderItem = groupValue => {
return {
value: groupValue,
label: groupValue
};
};
export let createItem = filterText => {
return {
value: filterText,
label: filterText
};
};
export let getOptionLabel = (option, filterText) => {
return option.isCreator ? `Create \"${filterText}\"` : option.label;
};
export let getSelectionLabel = option => {
if (option) return option.label;
};
export let getGroupHeaderLabel = option => {
return option.label;
};
export function handleClear() {
selectedValue = undefined;
listOpen = false;
dispatch("clear", selectedValue);
handleFocus();
}
export function handleClear() {
selectedValue = undefined;
listOpen = false;
dispatch("clear", selectedValue);
handleFocus();
}
export let loadOptions = undefined; // if used must return a Promise that updates 'items'
Styling
You can style a component by overriding the available CSS variables.
<script>
import Select from 'svelte-select';
const items = ['One', 'Two', 'Three'];
</script>
<style>
.themed {
--border: 3px solid blue;
--borderRadius: 10px;
--placeholderColor: blue;
}
</style>
<div class="themed">
<h2>Theming</h2>
<Select {items}></Select>
</div>
You can also use the inputStyles
prop to write in any override styles needed for the input.
<script>
import Select from 'svelte-select';
const items = ['One', 'Two', 'Three'];
</script>
<Select {items} inputStyles="box-sizing: border-box;"></Select>
Events
Event Name | Callback | Description |
---|---|---|
select | selectedValue | fires when selectedValue changes |
clear | - | fires when clear all is invoked |
error | { type, details } | fires when error is caught |
<script>
import Select from 'svelte-select';
let items = [...];
function handleSelect(selectedVal) {
...
}
function onClear() {
...
}
</script>
<Select {items} on:select={handleSelect} on:clear={handleClear}></Select>
Development
yarn global add serve@8
yarn
yarn dev
yarn test:browser
In your favourite browser go to http://localhost:3000 and open devtools and see the console for the test output. When developing its handy to see the component on the page; comment out the select.$destroy();
on the last test in /test/src/index.js or use the test.only()
to target just one test.
For example:
test.only('when getSelectionLabel contains HTML then render the HTML', async (t) => {
const select = new Select({
target,
props: {
selectedValue: items[0],
getSelectionLabel: (option) => `<p>${option.label}</p>`,
}
});
t.ok(document.querySelector('.selection').innerHTML === '<p>Chocolate</p>');
//select.$destroy();
});
Configuring webpack
If you're using webpack with svelte-loader, make sure that you add "svelte"
to resolve.mainFields
in your webpack config. This ensures that webpack imports the uncompiled component (src/index.html
) rather than the compiled version (index.mjs
) โ this is more efficient.
If you're using Rollup with rollup-plugin-svelte, this will happen automatically.