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
Prop | Type | Default | Description |
---|
items | String | - | Array of items |
filterText | String | - | Text to filter list labels by |
placeholder | String | - | Placeholder text |
optionIdentifier | String | 'value' | Override default identifier |
listOpen | Boolean | false | Open/close list |
containerStyles | String | - | Add/override container styles |
selectedValue | - | - | Selected value(s) |
isClearable | Boolean | true | Enable clearing selected items |
isCreatable | Boolean | false | Enable creating selected items |
isDisabled | Boolean | false | Disable select |
isMulti | Boolean | false | Enable multi select |
isSearchable | Boolean | true | Disable search/filtering |
isVirtualList | Boolean | false | Uses svelte-virtual-list to render list (experimental) |
groupBy | Function | - | Function to group list items |
groupFilter | Function | (groups) => groups | Group filter function |
isGroupHeaderSelectable | Boolean | false | Enable selectable group headers |
createGroupHeaderItem | Function | (groupValue) => { label:groupValue, value:groupValue } | create item for group headers |
createItem | Function | (filterText) => { label:filterText, value:filterText } | create item function |
getOptionLabel | Function | (option, filterText) => option.isCreator ? `Create "${filterText}"` : option.label | Get option label function |
getSelectionLabel | Function | (option) => option.label | Get selection label function |
getGroupHeaderLabel | Function | (option) => option.label | Get group header label function |
handleClear | Function | - | Clears selection, closes list and dispatches event |
Item | Component | Item | Item component |
Selection | Component | Selection | Selection component |
MultiSelection | Component | MultiSelection | Multi selection component |
loadOptions | Promise | - | Method that returns a Promise that updates items |
noOptionsMessage | String | 'No options' | Message to display when there are no items |
hideEmptyState | Boolean | false | Hide list when no options |
menuPlacement | String | 'auto' | When 'auto' displays either 'top' or 'bottom' depending on viewport |
hasError | Boolean | false | Show error styles around select input (red border) |
inputAttributes | Object | - | Pass in attributes like 'id' to the Select input, for example {id: 'Food Selection', foo: 'something'} |
listAutoWidth | Boolean | true | List width will grow wider than the Select container (depending on list item content length) |
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>
Events
Event Name | Callback | Description |
---|
select | selectedValue | fires when selectedValue changes |
clear | - | fires when clear all is invoked |
<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>');
});
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.
License
LIL