Breaking: Svelte 5

[Antosik]

Work in progress

Breaking changes

1. The svelte dependency has been moved to peer dependencies.
2. svelte@^5.8.0 is now required
3. Events and slot names have been updated to align with the new Svelte paradigm (see below). However, there are some breaking changes:
   3.1. The onchange event now triggers only on the component itself, not on the input element (to avoid event overlap)
   3.2. selected slot was renamed to selectedItem

Events

Events are now divided into two categories: native events - MultiSelectNativeEvents (triggered on the input element) and generated events - MultiSelectComponentEvents (triggered on the component itself).
Event naming conventions have been slightly adjusted (e.g., on:add → onadd), and custom event details are no longer required (e.g., e.detail.type → e.type).

Example

Before (svelte4):

<MultiSelect
  options={[1, 2, 3]}
  on:keyup={(event) => console.log('key', event.target.value)}
  on:change={(e) => alert(`You ${e.detail.type} ${e.detail.option}`)}
/>

After (svelte5):

<MultiSelect
  options={[1, 2, 3]}
  onkeyup={(event) => console.log('key', event.target.value)}
  onchange={(e) => alert(`You ${e.type} ${e.option}`)}
/>

Slots Snippets

Slot names have been slightly adjusted (e.g., expand-icon → expandIcon, etc.).

Example

Before (svelte4):

<MultiSelect
  options={languages}
  maxSelect={5}
  placeholder="What languages do you know?"
  selected={['Python', 'TypeScript', 'Julia']}
  let:option
>
  <LanguageSlot {option} />
  <Icon slot="expand-icon" let:open icon={open ? 'Collapse' : 'Expand'} />
  <MinusIcon slot="remove-icon" width="1em" />
</MultiSelect>

After (svelte5):

<MultiSelect
  options={languages}
  maxSelect={5}
  placeholder="What languages do you know?"
  selected={['Python', 'TypeScript', 'Julia']}
>
  {#snippet children({ option })}
    <LanguageSlot {option} />
  {/snippet}
  {#snippet expandIcon({ open })}
    <Icon icon={open ? 'Collapse' : 'Expand'} />
  {/snippet}
  {#snippet removeIcon()}
    <MinusIcon width="1em" />
  {/snippet}
</MultiSelect>

Minor changes

• Dependencies were updated to latest versions
• MultiSelectEvents were removed in favor of MultiSelectComponentEvents & MultiSelectNativeEvents
• Little code optimizations

Todos

1. Migrate remaining events to svelte5 (remove legacy code)
2. Migrate routes directory to svelte5
3. Update docs
4. Update tests (using @testing-library/svelte (?))
5. Wait until Feat/ svelte 5 upgrade mattjennings/mdsvexamples#32 is merged (before that dependencies can be installed only by using --legacy-peer-deps flag)
6. Update css-classes example to use :where
7. Update repl links on examples

Checklist

[ ] has tests (only needed if any new functionality was added or bugs fixed)
[ ] has examples/docs (only needed if any new functionality was added)

Useful links

• Svelte 5 Migration Guide

[janosh]

thanks so much @Antosik for taking of this big migration effort! 👍

i've been meaning to tackle this as well but haven't gotten to it yet so really appreciated 🙏

[janosh]

i don't think contributors need to run npm run package?

[Antosik]

Running npm run dev requires calling npm run package first. Without it, SvelteKit can’t load the library from the dist folder, resulting in an error like:

[plugin:vite:import-analysis] Failed to resolve entry for package "svelte-multiselect". The package may have incorrect main/module/exports specified in its package.json.

[janosh]

oh, good call! i think having the package import itself may be an antipattern. i mainly did it so that the mdsvexample code fences show the package name as users would write it instead of $lib

- import MultiSelect from '$lib'
+ import MultiSelect from 'svelte-multiselect'

[janosh]

ideally, i would like to stick to pure vitest unit testing. can we do without @testing-library

[Antosik]

I referenced @testing-library based on the docs:

While the process is very straightforward, it is also low level and somewhat brittle, as the precise structure of your component may change frequently. Tools like @testing-library/svelte can help streamline your tests.

That said, I’m ready to revert to pure Vitest if you prefer it.

[janosh]

yes please. i've been using pure vitest on several different projects and so far it's been great. haven't felt the need for additional testing packages and like to keep things lean.

[janosh]

maybe we can get rid of this file entirely now with runes? never liked this hacky workaround for testing 2-way binding...

[Antosik]

I’m not entirely sure about that. The docs mention:

When writing component tests that involve two-way bindings, context, or snippet props, it’s best to create a wrapper component for your specific test and interact with that. @testing-library/svelte contains some examples.

Looks like we still need to keep it for now…

[janosh]

ah bummer! thanks for digging this up! 👍

[janosh]

this file contains a lot of boilerplate. many of the functions are 1-liners so probably better to inline them

[Antosik]

These are purely utility functions to improve test readability and keep things consistent. But if you’d prefer, I can inline them instead.

[janosh]

yes, please inline. thank you!

[janosh]

great news! 🎉 mdsvexamples just added Svelte 5 support so no longer blocked from updating by the docs

[janosh]

did some more work. getting close to ready to merge. all unit tests now passing. some playwright tests still failing and some docs still need updating (like renaming slots to snippets)

[janosh]

this was a big lift! thanks for all your hard work @Antosik 👍 and sorry for the long delay in getting this over the finish line