Migration from v3
The v4.0 release of Svelecte is almost complete rewrite. This gave me opportunity to start fresh and write things more correct/elegant way, which will much easier to reason about and work with. So breaking changes were inevitable to pursue this goal of simplicity and maintainability breaking changes are relatively huge - ranging from HTML markup and CSS props to dropped/merged properties and changes what can be defined in specific properties. It’s all for the best.
Changed exports
Previously globally available function addFormatter has been renamed to addRenderer to be inline with renderer property.
import { addFormatter } from 'svelecte';
import { addRenderer } from 'svelecte';import { addFormatter } from 'svelecte';
import { addRenderer } from 'svelecte';Exported property TAB_SELECT_NAVIGATE has been removed due to added types. Now selectOnTab offers correct values to set.
<script>
import Svelecte, { TAB_SELECT_NAVIGATE } from 'svelecte';
import Svelecte from 'svelecte';
</script>
<Svelecte selectOnTab={TAB_SELECT_NAVIGATE} />
<Svelecte selectOnTab="select-navigate" /><script>
import Svelecte, { TAB_SELECT_NAVIGATE } from 'svelecte';
import Svelecte from 'svelecte';
</script>
<Svelecte selectOnTab={TAB_SELECT_NAVIGATE} />
<Svelecte selectOnTab="select-navigate" />Changed properties
Properties which have different set of possible values.
fetch
fetch now accepts ONLY strings. Due to inner rewrite, you can’t really rewrite underlying fetch requesing logic as was possible in v3. If you need to further customize
fetch props, you can set them in fetchProps property. Refer to fetch page for more details.
<script>
// options for Fetch API Request constructor
const fetchProps = {
headers: {
Authorization: 'bearer my-query',
'X-Requested-With': 'my-custom-header'
}
}
// my custom fetch
function myFetch(query) {
return fetch(`/api?query=${query}`, fetchProps)
.then((res) => res.json());
}
</script>
<Svelecte fetch={myFetch} />
<Svelecte fetch="/api?query=[query]" fetchProps={props} /><script>
// options for Fetch API Request constructor
const fetchProps = {
headers: {
Authorization: 'bearer my-query',
'X-Requested-With': 'my-custom-header'
}
}
// my custom fetch
function myFetch(query) {
return fetch(`/api?query=${query}`, fetchProps)
.then((res) => res.json());
}
</script>
<Svelecte fetch={myFetch} />
<Svelecte fetch="/api?query=[query]" fetchProps={props} />collapseSelection
Previously a boolean, now the type of collapsing must be specified (null, 'blur' or 'always'). Basically it merges together properties collapseSelection and alwaysCollapsed.
<Svelecte collapseSelection />
<Svelecte collapseSelection="blur" /><Svelecte collapseSelection />
<Svelecte collapseSelection="blur" />createFilter
This function now accepts just one parameter, inputValue: string and returns boolean
function createFilter(inputValue, options) {}
function createFilter(inputValue) {}function createFilter(inputValue, options) {}
function createFilter(inputValue) {} createTransform
This function has been renamed to createHandler and instead of 4 arguments it received one argument object with the same props.
Also this function can be async.
function myCreateTransform(inputValue, prefix, valueField, labelField) {...}
async function myAsyncCreateHandler({ inputValue, prefix, valueField, labelField }) { ... }
<Svelecte createTransform={myCreateTransform} />
<Svelecte createHandler={myAsyncCreateHandler} />function myCreateTransform(inputValue, prefix, valueField, labelField) {...}
async function myAsyncCreateHandler({ inputValue, prefix, valueField, labelField }) { ... }
<Svelecte createTransform={myCreateTransform} />
<Svelecte createHandler={myAsyncCreateHandler} />Removed properties
Some properties were removed and in most cases, replacement exists, will be always shown or linked to.
controlItem
This property has been dropped in favor to named slot selection. Main difference here is that slot exposes selectedOptions property. See Rendering page for more details about exposed properties.
<Svelecte controlItem={MyComponent} {...otherProps}>
<Svelecte {...otherProps} >
<svelte:fragment slot="selection" let:selectedOptions let:bindItem let:labelField>
{#each selectedOptions as item(item.value)}
<MyItem {item} {bindItem} labelProp={labelField}/>
{/each}
</svelte:fragment>
</Svelecte><Svelecte controlItem={MyComponent} {...otherProps}>
<Svelecte {...otherProps} >
<svelte:fragment slot="selection" let:selectedOptions let:bindItem let:labelField>
{#each selectedOptions as item(item.value)}
<MyItem {item} {bindItem} labelProp={labelField}/>
{/each}
</svelte:fragment>
</Svelecte>dropdownItem
This property has been dropped in favor to named slot option with exposed item property. Againg refer to Rendering page for more details.
<Svelecte dropdownItem={MyComponent} {...otherProps}>
<Svelecte {...otherProps} >
<svelte:fragment slot="option" let:item>
<MyDropdownItem {item} />
</svelte:fragment>
</Svelecte><Svelecte dropdownItem={MyComponent} {...otherProps}>
<Svelecte {...otherProps} >
<svelte:fragment slot="option" let:item>
<MyDropdownItem {item} />
</svelte:fragment>
</Svelecte>alwaysCollapsed
This property has been merged into property collapseSelection which now accepts null, 'blur' or 'always' value. With this
change new slot list-header has been added to allow customize selection rendering directly in the dropdown,
although implementing it is optional.
But if you were using it in v3, you need to implement it to keep it the same.
<Svelecte collapseSelection alwaysCollapsed />
<Svelecte collapseSelection="always" bind:readSelection>
<div slot="list-header" class="sv-control--selection" >
{#each readSelection as opt (opt.id)}
<!-- your rendering -->
{/each}
</div>
</Svelecte><Svelecte collapseSelection alwaysCollapsed />
<Svelecte collapseSelection="always" bind:readSelection>
<div slot="list-header" class="sv-control--selection" >
{#each readSelection as opt (opt.id)}
<!-- your rendering -->
{/each}
</div>
</Svelecte>searchField
This property has been dropped in favour of extend search-related settings. Refer to Searching page for more options.
sortField
This property has been dropped in favour of extend search-related settings. Refer to Searching page for more options.
disableSifter
This property has been dropped in favour of extend search-related settings. Refer to Searching page for more options.
style
Removed. Styling with CSS variables is recommended way to customize component visuals.
labelAsValue
This property has no replacement. Now when simple array (strings, no objects) are passed as options prop, it is converted internally like this:
options = ['One', 'Two', 'Three'];
// v3 conversion
options = [
{value: 0, text: 'One'},
{value: 1, text: 'Two'},
{value: 2, text: 'Three'}
];
// v4 conversion
options = [
{value: 'One', text: 'One'},
{value: 'Two', text: 'Two'},
{value: 'Three', text: 'Three'}
];options = ['One', 'Two', 'Three'];
// v3 conversion
options = [
{value: 0, text: 'One'},
{value: 1, text: 'Two'},
{value: 2, text: 'Three'}
];
// v4 conversion
options = [
{value: 'One', text: 'One'},
{value: 'Two', text: 'Two'},
{value: 'Three', text: 'Three'}
];Slots
indicator-icon
This slot has been renamed to dropdown-toggle and also it’s exposed property has been changed
<slot name="indicator-icon" let:hasDropdownOpened>
<slot name="dropdown-toggle" let:isOpen><slot name="indicator-icon" let:hasDropdownOpened>
<slot name="dropdown-toggle" let:isOpen>CSS
Due to markup changes you can expect that everything changed. But on the bright side, CSS theming is now fully supported and hopefully sufficient enough. If you miss something, raise an issue or open new discussion.
Check the details on Theme page.
Global config
collapseSelectionFn
Property has been dropped in favour of collapsedSelection slot. By default it still uses i18n.collapseSelection.
closeAfterSelect
Default value changed from false to 'auto'. Auto meand v3 default behaviour. true or false represents
enforcing behavior.
selectOnTab
Default value changed from null to false.