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>');

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

License

LIL