lipe-dev / svelte-select

Svelte Select. A select component for Svelte

Svelte Select

A select/autocomplete/typeahead Svelte component.

Demos

💥 Examples of every prop, event, slot and more 💥

✨ REPL: Simple ✨

💃 REPL: Show me everything 🕺

Installation

npm install svelte-select

Upgrading to v5

See migration guide if upgrading from v4 to v5.

Rollup and low/no-build setups

List position and floating is powered by floating-ui, see their package-entry-points docs if you encounter build errors.

Props

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

Named slots

<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>

Events

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

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} />

Async 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} />

Advanced List Positioning / Floating

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} />

Exposed methods

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={...}
    />

A11y (Accessibility)

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.`;
}

CSS custom properties (variables)

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>

🧪 Experimental: Replace styles (Tailwind, Bootstrap, Bulma etc)

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.

License

LIL