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 value = {value: 'cake', label: 'Cake'};

  function handleSelect(event) {
    console.log('selected item', event.detail);
    // .. do something here 🙂
  }
</script>

<Select {items} {value} on:select={handleSelect}></Select>

API

• id: String Default: null. Add an id to the input field.
• items: Array Default: []. List of selectable items that appear in the dropdown.
• value: Any Default: null. Selected item or items.
• filterText: String Default: ''. Text to filtering and searching items by.
• placeholder: String Default: 'Select...'. Placeholder text.
• noOptionsMessage: String Default: 'No options'. Message to display in list when there are no items.
• optionIdentifier: String Default: 'value'. Override default identifier.
• labelIdentifier: String Default: 'label'. Override default identifier.
• listOpen: Boolean Default: false. Open/close list.
• hideEmptyState: Boolean Default: false. Hide list and don't show noOptionsMessage when there are no items.
• 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 to value.
• isDisabled: Boolean Default: false. Disable select.
• isMulti: Boolean Default: false. Enable multi-select, value becomes an array of selected items.
• isFilterable: Boolean Default: true. Enable filtering of items via filterText.
• isSearchable: Boolean Default: true. Enable searching of items via filterText.
• isGroupHeaderSelectable: Boolean Default: false. Enable selectable group headers in items (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: {}. Pass in HTML attributes 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.
• ClearIcon Default: ClearIcon. ClearIcon component.
• isVirtualList: Boolean Default: false. Uses svelte-virtual-list to render list (experimental).
• filteredItems: Array Default: []. List of items that are filtered by filterText
• placeholderAlwaysShow: Boolean Default: false. When isMulti then placeholder text will always still show.
• isWaiting: Boolean Default: false. If true then loader shows. loadOptions will automatically set this as true until promise resolves.
• listOffset: Number Default: 5. Controls the spacing offset between the list and the input.

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 optionIdentifier = 'id';
  const labelIdentifier = 'title';

  const items = [
    {id: 0, title: 'Foo'},
    {id: 1, title: 'Bar'},
  ];
</script>

<Select {optionIdentifier} {labelIdentifier} {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} />

Exposed methods

These internal functions are exposed 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 searchScore = (label, filterText, item) => {
    if (filterText === '') return Number.MAX_VALUE;
    label = label.toLowerCase().trim();
    filterText = filterText.toLowerCase().trim();
    let matches = 0;
    for (let i = 0; i < label.length && i < filterText.length; ++i) {
        if (label[i] === filterText[i]) matches++;
    }
    return matches;
};

export let groupBy = undefined;

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() {
  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;
};

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

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	{ detail }	fires when value changes
clear	{ detail }	fires when clear all is invoked or item is removed (by user) from multi select
loaded	{ items }	fires when loadOptions resolves
error	{ type, details }	fires when error is caught

<script>
  import Select from 'svelte-select';

  let items = [...];
  function handleSelect(event) {
    // event.detail will contain the selected value
    ...
  }
  function handleClear(event) {
    // event.detail will be null unless isMulti is true and user has removed a single item
    ...
  }
</script>

<Select {items} on:select={handleSelect} on:clear={handleClear}></Select>

Filtering and searching

There are is an important distinction between filtering and searching. Filtering is binary - an item is either shown or hidden. Search results are displayed sorted according to a numeric score between the item and the textFilter. The default implementation of the search function is pretty basic and is not very flexible in terms of fuzzy string search, but an external library that provides a fuzzy string search scoring mechanism could be used instead.

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: {
      value: 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 — this is more efficient.

If you're using Rollup with rollup-plugin-svelte, this will happen automatically.

License

LIL