Product
Introducing SSO
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
svelte-select
Advanced tools
Changelog
5.8.3
Readme
💥 Examples of every prop, event, slot and more 💥
npm install svelte-select
See migration guide if upgrading from v4 to v5.
List position and floating is powered by floating-ui
, see their package-entry-points docs if you encounter build errors.
Prop | Type | Default | Description |
---|---|---|---|
items | any[] | [] | Array of items available to display / filter |
value | any | null | Selected value(s) |
justValue | any | null | READ-ONLY Selected value(s) excluding container object |
itemId | string | value | Override default identifier |
label | string | label | Override default label |
id | string | null | id attr for input field |
filterText | string | '' | Text to filter items by |
placeholder | string | Please select | Placeholder text |
hideEmptyState | boolean | false | When no items hide list |
listOpen | boolean | false | Open/close list |
class | string | '' | container classes |
containerStyles | string | '' | Add inline styles to container |
clearable | boolean | true | Enable clearing of value(s) |
disabled | boolean | false | Disable select |
multiple | boolean | false | Enable multi-select |
searchable | boolean | true | If false search/filtering is disabled |
groupHeaderSelectable | boolean | false | Enable selectable group headers |
focused | boolean | false | Controls input focus |
listAutoWidth | boolean | true | If false will ignore width of select |
showChevron | boolean | false | Show chevron |
inputAttributes | object | {} | Pass in HTML attributes to Select's input |
placeholderAlwaysShow | boolean | false | When multiple placeholder text will always show |
loading | boolean | false | Shows loading-icon . loadOptions will override this |
listOffset | number | 5 | px space between select and list |
debounceWait | number | 300 | milliseconds debounce wait |
floatingConfig | object | {} | Floating UI Config |
hasError | boolean | false | If true sets error class and styles |
name | string | null | Name attribute of hidden input, helpful for form actions |
required | boolean | false | If Select is within a <form> will restrict form submission |
multiFullItemClearable | boolean | false | When multiple selected items will clear on click |
closeListOnChange | boolean | true | After on:change list will close |
clearFilterTextOnBlur | boolean | true | If false , filterText value is preserved on:blur |
<Select>
<div slot="prepend" />
<div slot="selection" let:selection let:index /> <!-- index only available when multiple -->
<div slot="clear-icon" />
<div slot="multi-clear-icon" />
<div slot="loading-icon" />
<div slot="chevron-icon" />
<div slot="list-prepend" />
<div slot="list" let:filteredItems />
<div slot="list-append" />
<div slot="item" let:item let:index />
<div slot="input-hidden" let:value />
<div slot="required" let:value />
<!-- Remember you can also use `svelte:fragment` to avoid a container DOM element. -->
<svelte:fragment slot="empty" />
</Select>
Event Name | Callback | Description |
---|---|---|
change | { detail } | fires when the user selects an option |
input | { detail } | fires when the value has been changed |
focus | { detail } | fires when select > input on:focus |
blur | { detail } | fires when select > input on:blur |
clear | { detail } | fires when clear is invoked or item is removed (by user) from multi select |
loaded | { options } | fires when loadOptions resolves |
error | { type, details } | fires when error is caught |
filter | { detail } | fires when listOpen: true and items are filtered |
hoverItem | { detail } | fires when hoverItemIndex changes |
items
can be simple arrays or collections.
<script>
import Select from 'svelte-select';
let simple = ['one', 'two', 'three'];
let collection = [
{ value: 1, label: 'one' },
{ value: 2, label: 'two' },
{ value: 3, label: 'three' },
];
</script>
<Select items={simple} />
<Select items={collection} />
They can also be grouped and include non-selectable items.
<script>
import Select from 'svelte-select';
const items = [
{value: 'chocolate', label: 'Chocolate', group: 'Sweet'},
{value: 'pizza', label: 'Pizza', group: 'Savory'},
{value: 'cake', label: 'Cake', group: 'Sweet', selectable: false},
{value: 'chips', label: 'Chips', group: 'Savory'},
{value: 'ice-cream', label: 'Ice Cream', group: 'Sweet'}
];
const groupBy = (item) => item.group;
</script>
<Select {items} {groupBy} />
You can also use custom collections.
<script>
import Select from 'svelte-select';
const itemId = 'id';
const label = 'title';
const items = [
{id: 0, title: 'Foo'},
{id: 1, title: 'Bar'},
];
</script>
<Select {itemId} {label} {items} />
To load items asynchronously then loadOptions
is the simplest solution. Supply a function that returns a Promise
that resolves with a list of items. loadOptions
has debounce baked in and fires each time filterText
is updated.
<script>
import Select from 'svelte-select';
import { someApiCall } from './services';
async function examplePromise(filterText) {
// Put your async code here...
// For example call an API using filterText as your search params
// When your API responds resolve your Promise
let res = await someApiCall(filterText);
return res;
}
</script>
<Select loadOptions={examplePromise} />
svelte-select
uses floating-ui to control the list floating. See their docs and pass in your config via the floatingConfig
prop.
<script>
import Select from 'svelte-select';
let floatingConfig = {
strategy: 'fixed'
}
</script>
<Select {floatingConfig} />
These internal functions are exposed to override if needed. 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;
export let groupFilter = groups => groups;
export let createGroupHeaderItem = groupValue => {
return {
value: groupValue,
label: groupValue
};
};
export function handleClear() {
value = undefined;
listOpen = false;
dispatch("clear", value);
handleFocus();
}
export let loadOptions = undefined; // if used must return a Promise that updates 'items'
/* Return an object with { cancelled: true } to keep the loading state as active. */
export const getFilteredItems = () => {
return filteredItems;
};
export let debounce = (fn, wait = 1) => {
clearTimeout(timeout);
timeout = setTimeout(fn, wait);
};
Override core functionality at your own risk! See (get-items.js & filter.js)
// core replaceable methods...
<Select
filter={...}
getItems={...}
/>
Override these methods to change the aria-context
and aria-selection
text.
export let ariaValues = (values) => {
return `Option ${values}, selected.`;
}
export let ariaListOpen = (label, count) => {
return `You are currently focused on option ${label}. There are ${count} results available.`;
}
export let ariaFocused = () => {
return `Select is focused, type to refine list, press down to open the menu.`;
}
You can style a component by overriding the available CSS custom properties.
<script>
import Select from 'svelte-select';
</script>
<Select --border-radius= "10px" --placeholder-color="blue" />
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>
If you'd like to supply your own styles use: import Select from 'svelte-select/no-styles/Select.svelte'
. Then somewhere in your code or build pipeline add your own. There is a tailwind stylesheet via import 'svelte-select/tailwind.css'
. It uses @extend
so PostCSS is required.
FAQs
A <Select> component for Svelte apps
The npm package svelte-select receives a total of 20,400 weekly downloads. As such, svelte-select popularity was classified as popular.
We found that svelte-select demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.