README.md

Svelte SuggestBox

Svelte SuggestBox is a dropdown list component built with Svelte.

The Svelte SuggestBox can be customised in a lot of ways that should cover most of the possible use cases.

Features

• Combobox behaviour.
• Multiple item selection and allow duplicates.
• Custom behaviour for item suggestions.
• Custom display field, and search field.
• A custom layout for:
  • dropdown items.
  • selected items.
  • trigger button.
  • result count and "not found" messages.

Installation

yarn add svelte-suggestbox

or

npm install svelte-suggestbox --save

Get started

<script>
import SuggestBox from 'svelte-suggestbox';
</script>

<SuggestBox
placeholder={"Select an item"}
items={[{name: "Hello"}, {name: "World"}, {name: "It's me"}]}
/>

Demo

Examples available at

Props

Prop	Type	Description
placeholder	string	Placeholder for input.
items	array	A fixed set for dropdown menu elements. All array items must be of a JSON type.
displayField	function(item)	Returns a field value for supplied item. This value is used to lookup user input value in. Also to show in the dropdown and as a selected item(s). By default it will return name field value. default value: displayField = function(item) { return item.name; } If you use a different field than name then you should replace this function by defining this prop.
indexOfValue	function(item, value)	Returns the first index at which user input value can be found in the item. default value: indexOfValue = function(item, value) { return displayField(item).toLowerCase().indexOf(value.toLowerCase()); } if you use different logic to lookup user input value in items then you should define this prop. For instance, by default this function is Case Insensitive, if you want to make it Case Sensitive then you can change to: indexOfValue = {function(item, value) { return displayField(item).indexOf(value); } }
isSuggested	function(item, value)	Returns true or false indicating weather an item should be shown in the dropdown list. default value: isSuggested = function(item, value) { return indexOfValue(item, value) > -1; }
getSuggestedItems	function(value)	Returns an array of suggested dropdown list items. If user input value is empty returns all items. If there is a user input value then it filters out items using functions shown above. Also items get sorted using functions shown below. default value: getSuggestedItems = function(value) { return items.map((item, index) => ({ ...item, [INDEX_FIELD]: index })).filter(item => hideSelected && selectionMap[item[INDEX_FIELD]] ? false : value && value.length && enableInput ? isSuggested(item, value) : true ).sort(sortComparator);} This function can be replaced to change suggestions behaviour. But if you do so note that all the functions described above and the items array will be ignored. This prop can be used for XHR requests, so filtering and sorting will be handled on a server side.
sortField	function(item)	Returns a field value for supplied item. This value is used to sort items before showing in the dropdown. default value: sortField = function(item) { return item.name; } Same as the displayField this function returns name field. If you want to sort by a different field value then, you should replace this function. For instance, if you want to preserve initial items array order, you can use $index$ field that holds reference to items array index, so: sortField = function(item) { return item['$index$']; } will show dropdown items in the same order they are in items array.
sortComparator	function	sorting logic for suggested items default value: sortComparator = function(a, b) { return sortField(a) > sortField(b) ? 1 : sortField(a) < sortField(b) ? -1 : 0; }
callDelay	integer	A number of milliseconds to wait before calling getSuggestedItems. Can be useful with XHR requests. Default value is 0. The dropdown will show waiting message for callDelay number of milliseconds.
enableInput	boolean	default true. Enables user to input a lookup value. Set to false for combobox behaviour.
typeAhead	boolean	default true. When there is only one suggested item left, it will fill the rest of the value into the input.
multiSelect	boolean	default false.
allowDuplicates	boolean	default false.
closeOnSelect	boolean	default true.
hideSelected	boolean	default true.
selectedItems	array	an array of items that were selected.
cls	string	a CSS class that will be appended (if defined) to the parent DOM element

Slots

Name	Description	Slot Props
selected-item	Selected item layout	item, index, isFirst, isLast
trigger-button	Trigger button
fetching-msg	shows when callDelay > 0
result-count	shows number of dropdown items found
suggest-item	dropdown item
no-results-msg	shows when there are no dropdown items found

TODO:

• examples page on gh-pages
• demo page
• test mouse events
• test slots
• css variables for colors, width etc with fallback values
• typeAhead match from beginning only