### Clone Repository and Install Dependencies

Source: https://github.com/janosh/svelte-multiselect/blob/main/contributing.md

Clone the repository, navigate to the project directory, install npm dependencies, and start the development server.

```sh
git clone https://github.com/janosh/svelte-multiselect
cd svelte-multiselect
npm install
npm run dev
```

--------------------------------

### Install svelte-multiselect

Source: https://context7.com/janosh/svelte-multiselect/llms.txt

Install the svelte-multiselect package using npm or pnpm.

```bash
npm install svelte-multiselect
# or
pnpm add svelte-multiselect
```

--------------------------------

### Example: Alert on Option Change in Svelte

Source: https://github.com/janosh/svelte-multiselect/blob/main/readme.md

This example demonstrates how to use the `onchange` event to display alerts for various selection actions like adding, removing, selecting all, or reordering options.

```svelte
<MultiSelect
  onchange={({ type, option, options }) => {
    if (type === 'add') alert(`You added ${option}`)
    if (type === 'remove') alert(`You removed ${option}`)
    if (type === 'removeAll') alert(`You removed ${options}`)
    if (type === 'selectAll') alert(`You selected all: ${options}`)
    if (type === 'reorder') alert(`New order: ${options}`)
  }}
/>
```

--------------------------------

### MultiSelect as a Tagging Component (Start Empty)

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/allow-user-options/+page.md

Configure MultiSelect to start with no options, allowing users to populate it from scratch using `allowUserOptions="append"`. This effectively turns it into a tagging component. `noMatchingOptionsMsg` is set to empty and `createOptionMsg` to null for a cleaner tagging experience.

```svelte
<script lang="ts">
  import MultiSelect from '$lib'

  let selected: string[] = $state([])
</script>

{#if selected?.length > 0}
  <pre><code>selected = {JSON.stringify(selected)}</code></pre>
{/if}

<MultiSelect
  allowUserOptions="append"
  bind:selected
  noMatchingOptionsMsg=""
  createOptionMsg={null}
/>
```

--------------------------------

### Install Svelte MultiSelect

Source: https://github.com/janosh/svelte-multiselect/blob/main/readme.md

Install the svelte-multiselect package as a dev dependency using npm.

```sh
npm install --dev svelte-multiselect
```

--------------------------------

### Basic Nav Component Usage

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/nav/+page.md

Demonstrates the basic setup of the Nav component using an array of simple route strings. Auto-generated labels are used for each route.

```svelte
<script lang="ts">
  import { Nav } from '$lib'
  import { page } from '$app/state'

  const routes: string[] = ['/', '/about', '/contact', '/blog']
  const link_props = { onclick: (event: MouseEvent) => event.preventDefault() }
</script>

<Nav {routes} {page} {link_props} />
```

--------------------------------

### Event Handling Example

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/events/+page.md

Example demonstrating how to handle the `onadd` custom event with type safety using TypeScript.

```APIDOC
## Event Handling Tips

1. **Type Safety**: For better type checking in TypeScript projects, use the `MultiSelectEvents` interface:

   ```ts
   <script lang="ts">
    import type { MultiSelectEvents } from '$lib/types'

     const onadd: MultiSelectEvents['onadd'] = (data) => {
       console.log(`onadd`, data)
     }
   </script>

   <MultiSelect {onadd} options={[{ label: `foo` }]} />
   ```

   Native DOM event handlers like `onblur`, `onfocus`, `onkeydown`, etc. are forwarded from the `<input>` element and use standard DOM event types (e.g. `FocusEvent`, `KeyboardEvent`).

2. **Custom Options**: The `oncreate` event only fires when `allowUserOptions` is enabled and users type text that doesn't match existing options.

3. **New Events**: The `onsearch` event is debounced (150ms) to avoid excessive callbacks while typing. `onactivate` only fires during keyboard navigation (arrow keys), not on mouse hover. `onduplicate` only fires when `duplicates={false}` (the default).
```

--------------------------------

### Food Picker Component Example

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/ui/+page.md

Demonstrates configuring the MultiSelect component with dynamic background colors for options and setting various props like placeholder, removeAllTitle, closeDropdownOnSelect, and invalid state. This example is used for Playwright testing.

```svelte
<script lang="ts">
  import MultiSelect from '$lib'
  import { foods } from '$site/options'

  function random_color(): string {
    const r = Math.floor(Math.random() * 255)
    const g = Math.floor(Math.random() * 255)
    const b = Math.floor(Math.random() * 255)
    return `rgb(${r}, ${g}, ${b}`)
  }
</script>

<MultiSelect
  options={foods.map((label) => ({ label, style: `background-color: ${random_color()}` }))}
  placeholder="Pick your favorite foods"
  removeAllTitle="Remove all foods"
  closeDropdownOnSelect
  style="width: 500px"
  invalid
/>
```

--------------------------------

### Example Usage of Svelte Multiselect Snippets

Source: https://github.com/janosh/svelte-multiselect/blob/main/readme.md

This example demonstrates how to integrate multiple snippets for customizing options, the remove icon, and the loading spinner within a Svelte Multiselect component.

```svelte
<MultiSelect options={[`Red`, `Green`, `Blue`, `Yellow`, `Purple`]} >
  {#snippet children({ idx, option, type })} 
    <span style="display: flex; align-items: center; gap: 6pt">
      <span
        style:background={`${option}`}
        style="border-radius: 50%; width: 1em; height: 1em"
      ></span>
      {#if type === `option`}{idx + 1}{/if}
      {option}
    </span>
  {/snippet}
  {#snippet spinner()}
    <CustomSpinner />
  {/snippet}
  {#snippet removeIcon({ isRemoveAll })}
    <strong>{isRemoveAll ? `Clear` : `X`}</strong>
  {/snippet}
</MultiSelect>
```

--------------------------------

### Initialize Single Select with HTML Labels

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/min-max-select/+page.md

This example demonstrates initializing a single-select MultiSelect with HTML content in the labels, using the `parseLabelsAsHtml` prop. It also shows pre-selection via the `preselected` property on the option.

```svelte
<script lang="ts">
  // for https://github.com/janosh/svelte-multiselect/issues/249
  import MultiSelect from '$lib'
  import type { ObjectOption } from '$lib/types'

  const red_pill =
    `🔴  &ensp; Red Pill (<a href="https://wikipedia.org/wiki/Red_pill_and_blue_pill">what?</a>)`
  const blue_pill =
    `🔵  &ensp; Blue Pill &nbsp; <img height="35px" style="vertical-align: middle;" src="https://upload.wikimedia.org/wikipedia/en/a/ab/Morpheus.jpg" />`
  const options: ObjectOption[] = [{
    label: red_pill,
    value: `red pill`,
    preselected: true,
  }, {
    label: blue_pill,
    value: `blue pill`,
  }]

  let value: ObjectOption | null = $state(null)
</script>

<MultiSelect {options} maxSelect={1} parseLabelsAsHtml bind:value />
```

--------------------------------

### Interactive CopyButton Demo

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/(hide)/copy-button/+page.md

Use this example to test all states of the CopyButton, including ready, success, and error. It also demonstrates disabled behavior, empty content handling, and automatic reset timing. Configure reset duration and disable the button via input controls.

```svelte
<script lang="ts">
  import { CopyButton, tooltip } from '$lib'

  type Copy_state = `ready` | `success` | `error`

  let content = $state(`npm test`)
  let disabled = $state(false)
  let reset_sec = $state(2)
  let state = $state<Copy_state>(`ready`)
  let copied_value = $state(``)
  let copy_error = $state(``)
  let callback_events = $state<string[]>([])

  const labels = {
    ready: { icon: `Copy`, text: `ready` },
    success: { icon: `Check`, text: `success` },
    error: { icon: `Alert`, text: `error` },
  } as const

  const push_event = (event_name: string, payload: string): void => {
    callback_events = [`${event_name}: ${payload}`, ...callback_events].slice(0, 5)
  }

  const handle_copy_success = (copied_content: string): void => {
    copied_value = copied_content
    copy_error = ``
    push_event(`on_copy_success`, copied_content || `""`)
  }

  const handle_copy_error = (error: unknown): void => {
    const error_message = String(error)
    copy_error = error_message
    push_event(`on_copy_error`, error_message)
  }
</script>

<p style="display: flex; gap: 6pt; align-items: center; flex-wrap: wrap; margin: 0 0 8pt">
  <CopyButton
    {content}
    bind:state
    {disabled}
    {reset_sec}
    {labels}
    on_copy_success={handle_copy_success}
    on_copy_error={handle_copy_error}
  />
  <input bind:value={content} style="min-width: 16em" />
</p>

<div
  style="display: flex; gap: 12pt; align-items: center; flex-wrap: wrap; margin: 0 0 8pt; font-size: 0.9em"
>
  <label>
    <span
      style="cursor: help; text-decoration: underline dotted"
      {@attach tooltip({ content: `Zero or negative values disable auto-reset` })}
    >
      reset_sec:
    </span>
    <input type="number" min="-1" step="0.5" bind:value={reset_sec} style="width: 5em" />
  </label>
  <label>
    <input type="checkbox" bind:checked={disabled} />
    disabled
  </label>
</div>

<p><strong>Copied:</strong> {copied_value || `nothing yet`}</p>
{#if copy_error}
  <p><strong>Error:</strong> {copy_error}</p>
{/if}

<p style="margin: 8pt 0 0"><strong>Callback events:</strong></p>
{#if callback_events.length}
  <ul style="margin: 6pt 0 0; padding-left: 1.25em">
    {#each callback_events as callback_event}
      <li><code>{callback_event}</code></li>
    {/each}
  </ul>
{:else}
  <p style="margin: 6pt 0 0; opacity: 0.8">No callback events yet.</p>
{/if}
```

--------------------------------

### Configure Custom History Shortcuts

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/history/+page.md

Use the `shortcuts` prop to define custom keyboard shortcuts for undo and redo actions. This example sets undo to 'alt+z' and redo to 'alt+shift+z'.

```svelte
<MultiSelect
  history={true}
  shortcuts={{ undo: 'alt+z', redo: 'alt+shift+z' }}
/>
```

--------------------------------

### expandAllGroups

Source: https://github.com/janosh/svelte-multiselect/blob/main/readme.md

Programmatically expand all groups. Use with `bind:expandAllGroups` to get a callable function.

```APIDOC
## expandAllGroups

### Description
Programmatically expand all groups. Use with `bind:expandAllGroups` to get a callable function.

### Type
`() => void`

### Bindable
`bind:expandAllGroups`
```

--------------------------------

### LoadOptions Prop Configuration

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/infinite-scroll/+page.md

The `loadOptions` prop can be a simple fetch function or an object with configuration options like `debounceMs`, `batchSize`, and `onOpen`. This example shows the object configuration.

```typescript
// Simple: just a function
loadOptions={myFetchFn}

// With config: object with fetch + options
loadOptions={{ fetch: myFetchFn, debounceMs: 500, batchSize: 20, onOpen: false }}
```

--------------------------------

### Tooltip Text Wrapping and Width Adjustment

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/attachments/+page.md

Demonstrates how to control text wrapping and shrink-to-fit width for tooltips using the `--tooltip-max-width` CSS variable. Includes examples for balanced wrapping and handling long content.

```svelte
<!-- Text wrapping and shrink-to-fit width demo -->
<div style="display: flex; gap: 1em; margin: 2em 0; flex-wrap: wrap">
  <button
    style="--tooltip-max-width: 200px"
    {@attach tooltip({
      content: `This tooltip uses balanced text wrapping for even line lengths`,
      placement: `top`,
    })}
  >
    Balanced wrapping
  </button>
  <button
    style="--tooltip-max-width: 220px"
    {@attach tooltip({
      content:
        `Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.`,
      placement: `bottom`,
    })}
  >
    Long text shrink-to-fit
  </button>
</div>
```

--------------------------------

### Allowing Custom User Input in MultiSelect

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/allow-user-options/+page.md

Set `allowUserOptions` to `true` to let users add custom options by typing and pressing enter. This example shows how to create a new food option and provides feedback when a custom option is created.

```svelte
<script lang="ts">
  import MultiSelect, { Toggle } from '$lib'
  import { foods } from '$site/options'

  let selected: string[] = $state(
    '🍇 Grapes, 🍈 Melon, 🍉 Watermelon, 🍊 Tangerine'.split(', '),
  )
  let duplicates = $state(false)
  let last_created: string | null = $state(null)
</script>

<MultiSelect
  options={foods}
  allowUserOptions
  {duplicates}
  bind:selected
  createOptionMsg={({ searchText }) => `Add '${searchText}' as custom food`}
  oncreate={({ option }) => last_created = String(option)}
/>

{#if last_created}
  <p style="color: mediumseagreen; margin-top: 0.5em">
    ✓ Created custom option: {last_created}
  </p>
{/if}

<label for="duplicates" style="display: block; margin-top: 1em">
  Allow duplicates
  <Toggle bind:checked={duplicates} id="duplicates" />
</label>

<p style="margin-top: 0.5em">
  Selected ({selected.length}): {selected.join(', ') || 'none'}
</p>
```

--------------------------------

### Customize 'Select All' Label

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/min-max-select/+page.md

Provide a custom string to the `selectAllOption` prop to change the text of the 'Select all' button. This example also demonstrates using object options.

```svelte
<script lang="ts">
  import MultiSelect from '$lib'
  import type { ObjectOption } from '$lib/types'

  interface ColorOption extends ObjectOption {
    value: string
  }

  const colors: ColorOption[] = [
    { label: `Red`, value: `#ff6b6b` },
    { label: `Orange`, value: `#ffa94d` },
    { label: `Yellow`, value: `#ffd43b` },
    { label: `Green`, value: `#69db7c` },
    { label: `Blue`, value: `#4dabf7` },
    { label: `Purple`, value: `#9775fa` },
  ]
  let selected: ColorOption[] = $state([])
</script>

<MultiSelect options={colors} bind:selected selectAllOption="Add all colors" placeholder="Select colors..." />

<div style="display: flex; gap: 4px; margin-top: 8px; flex-wrap: wrap;">
  {#each selected as color}
    <span style="background: {color.value}; padding: 4px 8px; border-radius: 4px;">
      {color.label}
    </span>
  {/each}
</div>
```

--------------------------------

### collapseAllGroups

Source: https://github.com/janosh/svelte-multiselect/blob/main/readme.md

Programmatically collapse all groups. Use with `bind:collapseAllGroups` to get a callable function.

```APIDOC
## collapseAllGroups

### Description
Programmatically collapse all groups. Use with `bind:collapseAllGroups` to get a callable function.

### Type
`() => void`

### Bindable
`bind:collapseAllGroups`
```

--------------------------------

### Basic Multi-Select with String Options

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/site/Examples.md

Demonstrates a simple multi-select where users can choose multiple items from a predefined list of strings. Ensure the 'svelte-multiselect' library is imported.

```svelte
<script lang="ts">
  import MultiSelect from 'svelte-multiselect'

  const fruits: string[] = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry']
  let selected: string[] = $state([])
</script>

<MultiSelect id="fruits" bind:selected options={fruits} placeholder="Choose fruits..." />

<p>You selected: {JSON.stringify(selected)}</p>
```

--------------------------------

### Advanced Configuration for Dynamic Loading

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/infinite-scroll/+page.md

Customize the `loadOptions` behavior by passing an object with `fetch`, `debounceMs`, and `batchSize` properties for fine-grained control over data fetching.

```svelte
<script lang="ts">
  import MultiSelect from '$lib'
  import type { LoadOptionsParams, LoadOptionsResult } from '$lib/types'

  const all_items: string[] = Array.from(
    { length: 500 },
    (_, idx) => `Option ${idx + 1}`,
  )

  async function load_options(
    { search, offset, limit }: LoadOptionsParams,
  ): Promise<LoadOptionsResult<string>> {
    await new Promise((resolve) => setTimeout(resolve, 200))

    const filtered = search
      ? all_items.filter((item) => item.toLowerCase().includes(search.toLowerCase()))
      : all_items

    return {
      options: filtered.slice(offset, offset + limit),
      hasMore: offset + limit < filtered.length,
    }
  }
</script>

<MultiSelect
  loadOptions={{ fetch: load_options, debounceMs: 500, batchSize: 20 }}
  placeholder="Custom config (500ms debounce, 20 items per batch)" />
```

--------------------------------

### Nav Component with Dropdown Menus

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/nav/+page.md

Illustrates the creation of dropdown menus using tuple syntax `[parent, [children...]]`. A parent route becomes clickable if it is also present in its own children array.

```svelte
<script lang="ts">
  import { Nav } from '$lib'
  import { page } from '$app/state'

  const routes = [
    '/',
    ['/docs', ['/docs', '/docs/api', '/docs/guides']], // /docs is clickable (in children)
    ['/help', ['/help/faq', '/help/support']], // /help is just a label (not in children)
    '/about',
  ]
  const link_props = { onclick: (event: MouseEvent) => event.preventDefault() }
</script>

<Nav {routes} {page} {link_props} />
```

--------------------------------

### Get Handle to Main Input Element

Source: https://github.com/janosh/svelte-multiselect/blob/main/readme.md

Access the main `<input>` DOM element after the component has mounted. This is a bindable property.

```typescript
input: HTMLInputElement | null = null  // bindable
```

--------------------------------

### Get Currently Filtered Options

Source: https://github.com/janosh/svelte-multiselect/blob/main/readme.md

Read-only property that provides an array of `Option` objects currently matching the search text. This is a bindable property.

```typescript
matchingOptions: Option[] = []  // bindable
```

--------------------------------

### Get Handle to Outer Div Element

Source: https://github.com/janosh/svelte-multiselect/blob/main/readme.md

Obtain a reference to the outer wrapper `<div>` DOM element after the component mounts. This is a bindable property.

```typescript
outerDiv: HTMLDivElement | null = null  // bindable
```

--------------------------------

### Async Data Loading with Pagination

Source: https://context7.com/janosh/svelte-multiselect/llms.txt

Fetch options from a remote API on demand with automatic pagination. Configure debounce and batch size for optimal performance.

```svelte
<script lang="ts">
  import MultiSelect, { type LoadOptionsFn } from 'svelte-multiselect'

  interface Repo { label: string; value: string; description: string }

  const fetchRepos: LoadOptionsFn<Repo> = async ({ search, offset, limit }) => {
    const url = `https://api.github.com/search/repositories?q=${encodeURIComponent(search || 'svelte')}&per_page=${limit}&page=${Math.floor(offset / limit) + 1}`
    const res  = await fetch(url)
    const data = await res.json()
    return {
      options: (data.items ?? []).map((r: { full_name: string; description: string }) => ({
        label:       r.full_name,
        value:       r.full_name,
        description: r.description,
      })),
      hasMore: offset + limit < (data.total_count ?? 0),
    }
  }

  let selected = $state<Repo[]>([])
</script>

<MultiSelect
  loadOptions={{ fetch: fetchRepos, debounceMs: 400, batchSize: 20, onOpen: true }}
  bind:selected
  placeholder="Search GitHub repos…"
/>
```

--------------------------------

### Basic MultiSelect with String Options

Source: https://github.com/janosh/svelte-multiselect/blob/main/readme.md

Use the `options` prop with an array of strings for simple selection.

```svelte
<MultiSelect options={['Red', 'Green', 'Blue']} />
```

--------------------------------

### Get Handle to Hidden Form Input

Source: https://github.com/janosh/svelte-multiselect/blob/main/readme.md

Access the hidden form input element, typically used for validation purposes, after the component mounts. This is a bindable property.

```typescript
form_input: HTMLInputElement | null = null  // bindable
```

--------------------------------

### Defining Object Options

Source: https://context7.com/janosh/svelte-multiselect/llms.txt

Shows how to define options using an array of objects, including properties like 'label', 'value', 'group', 'preselected', 'disabled', and 'style'.

```svelte
<script lang="ts">
  import MultiSelect, { type ObjectOption } from 'svelte-multiselect'

  const options: ObjectOption[] = [
    { label: 'JavaScript', value: 'js', group: 'Frontend' },
    { label: 'TypeScript', value: 'ts', group: 'Frontend' },
    { label: 'Python',     value: 'py', group: 'Backend',  preselected: true },
    { label: 'Rust',       value: 'rs', group: 'Systems',  disabled: true, disabledTitle: 'Coming soon' },
    {
      label: 'Go',
      value: 'go',
      group: 'Backend',
      style: { option: 'color: #00ADD8', selected: 'background: #00ADD822' },
    },
  ]

  let selected = $state<ObjectOption[]>([])
</script>

<MultiSelect {options} bind:selected />
<!-- Python is pre-selected; Rust is shown but cannot be chosen -->
```

--------------------------------

### Enable 'Select All' Option with Keyboard Shortcut

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/min-max-select/+page.md

Use the `selectAllOption` prop to add a 'Select all' button. It respects `maxSelect` and can be triggered via keyboard shortcut using the `shortcuts` prop.

```svelte
<script lang="ts">
  import MultiSelect from '$lib'

  const fruits: string[] = [
    `Apple`,
    `Banana`,
    `Cherry`,
    `Date`,
    `Elderberry`,
    `Fig`,
    `Grape`,
  ]
  let selected: string[] = $state([])
</script>

<MultiSelect
  options={fruits}
  bind:selected
  selectAllOption
  shortcuts={{ select_all: `ctrl+a` }}
  maxSelect={5}
  placeholder="Pick your favorite fruits"
/>

<p>Selected ({selected.length}/5): {selected.join(`, `) || `none`}</p>
```

--------------------------------

### Multi-Select with Object Options

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/site/Examples.md

Shows how to use an array of objects for options, where each object has at least a 'label' and 'value' property. This allows for richer option data. Ensure the 'ObjectOption' type is imported if needed for type safety.

```svelte
<script lang="ts">
  import MultiSelect from 'svelte-multiselect'
  import type { ObjectOption } from '$lib/types'

  interface Country extends ObjectOption {
    value: string
    continent: string
  }

  const countries: Country[] = [
    { label: 'United States', value: 'US', continent: 'North America' },
    { label: 'Canada', value: 'CA', continent: 'North America' },
    { label: 'United Kingdom', value: 'UK', continent: 'Europe' },
    { label: 'Germany', value: 'DE', continent: 'Europe' },
    { label: 'Japan', value: 'JP', continent: 'Asia' },
  ]
  let selected: Country[] = $state([])
</script>

<MultiSelect
  id="countries"
  bind:selected
  options={countries}
  placeholder="Select countries..."
/>

<p>Selected countries: {selected.map((c) => c.label).join(', ')}</p>
<p>Country codes: {selected.map((c) => c.value).join(', ')}</p>
```

--------------------------------

### User Message Snippet

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/snippets/+page.md

Customize the user message displayed in the MultiSelect component using the `userMsg` snippet. This example shows conditional emoji rendering based on selection.

```svelte
<script lang="ts">
  import MultiSelect, { Icon } from '$lib'
  import { languages } from '$site/options'
  import { LanguageSnippet } from '$site'

  let selected: string[] = $state([`Python`, `TypeScript`, `Julia`])
  let searchText = $state(`Julia`)
</script>

<MultiSelect
  options={languages}
  bind:searchText
  bind:selected
  maxSelect={5}
  placeholder="What languages do you know?"
  open
  allowUserOptions
>
  {#snippet userMsg({ msg })}
    <span>{msg} {selected?.includes(searchText) ? '🤦' : '👷'}</span>
  {/snippet}
</MultiSelect>
```

--------------------------------

### Svelte: Handling Navigation Events with Callbacks

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/nav/+page.md

Manage navigation events and menu state changes using callbacks. The `onnavigate` callback can prevent navigation by returning `false`, while `onopen` and `onclose` track the burger menu's state.

```svelte
<script lang="ts">
  import { Nav } from '$lib'
  import { page } from '$app/state'

  const routes = ['/', '/about', '/contact', '/blog']
  const link_props = { onclick: (event: MouseEvent) => event.preventDefault() }
  let nav_message = $state('')
  let menu_status = $state('closed')
</script>

<div style="margin-bottom: 1em">
  <strong>Last action:</strong>
  {nav_message || 'None'} | <strong>Menu:</strong>
  {menu_status}
</div>

<Nav
  {routes}
  {page}
  {link_props}
  onnavigate={({ href }) => {
    nav_message = `Navigated to ${href}`
    return false // returning false prevents navigation
  }}
  onopen={() => (menu_status = 'open')}
  onclose={() => (menu_status = 'closed')}
/>
```

--------------------------------

### Draggable Elements with Callbacks

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/attachments/+page.md

Make elements draggable within a container. Supports custom handles and callbacks for drag start, drag, and drag end events. The default handle is the element itself.

```svelte
<script lang="ts">
  import { draggable } from '$lib'

  let last_drag: string = $state('')
</script>

<div class="drag-area">
  <!-- Absolute positioned box → default handle is the node itself -->
  <div
    class="drag-box"
    style="position: absolute; left: 1rem; top: 1rem"
    {@attach draggable({
      on_drag: (event: PointerEvent) =>
        last_drag = `${event.clientX}, ${event.clientY}`,
    })}
  >
    Drag me
    <small style="display: block; opacity: 0.7">this text is also draggable</small>
  </div>

  <!-- Second draggable with custom handle and callbacks -->
  <div
    class="drag-box"
    style="position: absolute; left: 12rem; top: 8rem; width: 14rem"
    {@attach draggable({
      handle_selector: `.drag-handle`,
      on_drag_start: () => last_drag = `start`,
      on_drag: (event: PointerEvent) =>
        last_drag = `${event.clientX}, ${event.clientY}`,
      on_drag_end: () => last_drag = `end`,
    })}
  >
    <div class="drag-handle">Drag with custom callbacks</div>
    <small style="display: block; opacity: 0.7">this text is not draggable</small>
  </div>
</div>

<p>last pointer: {last_drag || '—'}</p>

<style>
  .drag-area {
    position: relative;
    height: 40vh;
    border: 1px dashed rgba(255, 255, 255, 0.2);
    margin: 1rem 0;
    overflow: hidden;
  }
  .drag-box {
    background: rgba(255, 255, 255, 0.08);
    border: 1px solid rgba(255, 255, 255, 0.15);
    border-radius: 8px;
    padding: 0.6em 0.8em;
    width: max-content;
  }
</style>
```

--------------------------------

### Svelte: Custom Link Rendering with 'link' Snippet

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/nav/+page.md

Customize the rendering of all links within the Nav component by providing a `link` snippet. This example shows how to apply custom styling and prevent default navigation.

```svelte
<script lang="ts">
  import { Nav } from '$lib'
  import { page } from '$app/state'

  const routes = ['/', '/about', '/contact']
</script>

<Nav {routes} {page}>
  {#snippet link({ href, label, isActive })}
    <a
      {href}
      style:font-weight={isActive ? `bold` : `normal`}
      onclick={(event: MouseEvent) => event.preventDefault()}
    >🔗 {label}</a>
  {/snippet}
</Nav>
```

--------------------------------

### Dynamic Options Loading with REST API

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/infinite-scroll/+page.md

Connect to a real API by defining a `loadOptions` function that fetches user data. Includes a custom snippet for displaying user email alongside their name.

```svelte
<script lang="ts">
  import MultiSelect from '$lib'
  import type { LoadOptionsParams, LoadOptionsResult, ObjectOption } from '$lib/types'

  interface User extends ObjectOption {
    email: string
    id: number
  }

  // Simulated API
  async function fetch_users(
    { search, offset, limit }: LoadOptionsParams,
  ): Promise<LoadOptionsResult<User>> {
    await new Promise((resolve) => setTimeout(resolve, 400))

    // Simulated database
    const all_users: User[] = Array.from({ length: 2000 }, (_, idx) => ({
      label: `User ${idx + 1}`,
      email: `user${idx + 1}@example.com`,
      id: idx + 1,
    }))

    const filtered = search
      ? all_users.filter((user) =>
        user.label.toLowerCase().includes(search.toLowerCase()) ||
        user.email.toLowerCase().includes(search.toLowerCase())
      )
      : all_users

    return {
      options: filtered.slice(offset, offset + limit),
      hasMore: offset + limit < filtered.length,
    }
  }
</script>

<MultiSelect
  loadOptions={fetch_users}
  placeholder="Search users by name or email...">
  {#snippet children({ option })}
    <div>
      <strong>{option.label}</strong>
      <small style="opacity: 0.7; margin-left: 8px">{option.email}</small>
    </div>
  {/snippet}
</MultiSelect>
```

--------------------------------

### LoadOptions Prop Configuration

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/infinite-scroll/+page.md

Details the configuration options for the `loadOptions` prop, which can be a simple fetch function or an object with additional settings like debounce, batch size, and open behavior.

```APIDOC
## Props Reference

The `loadOptions` prop accepts either a function (simple) or an object (with config):

```typescript
// Simple: just a function
loadOptions={myFetchFn}

// With config: object with fetch + options
loadOptions={{ fetch: myFetchFn, debounceMs: 500, batchSize: 20, onOpen: false }}
```

| Config Key   | Type      | Default | Description                                 |
| ------------ | --------- | ------- | ------------------------------------------- |
| `fetch`      | `fn`      | —       | Async function to load options (required)   |
| `debounceMs` | `number`  | `300`   | Debounce delay for search queries           |
| `batchSize`  | `number`  | `50`    | Number of options to load per batch         |
| `onOpen`     | `boolean` | `true`  | Whether to load options when dropdown opens |

### LoadOptions Parameters

```typescript
interface LoadOptionsParams {
  search: string // Current search text
  offset: number // Number of options already loaded (for pagination)
  limit: number // Batch size to load
}

interface LoadOptionsResult<T> {
  options: T[] // Array of options to add
  hasMore: boolean // Whether more options are available
}
```

### Error Handling

If `loadOptions` throws or rejects, the error is logged to console and the component continues to function normally. The loading indicator will be hidden and users can retry by typing or scrolling.
```

--------------------------------

### Run the Full Test Suite

Source: https://github.com/janosh/svelte-multiselect/blob/main/contributing.md

Execute the complete test suite to ensure that your changes have not introduced any regressions. This is also run in the CI environment.

```sh
npm test
```

--------------------------------

### Simple HTML Tag as Remove Icon Snippet

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/snippets/+page.md

Utilize a simple HTML `<span>` element with custom text and styling for the remove icon. This example also demonstrates custom `selectedItem`, `option`, and `expandIcon` snippets.

```svelte
<script lang="ts">
  import MultiSelect, { Icon } from '$lib'
  import { languages } from '$site/options'
  import { LanguageSnippet } from '$site'

  // local variable used in CollapseIcon onclick callback to close dropdown
  let open = $state(false)
</script>

<MultiSelect
  options={languages}
  maxSelect={5}
  placeholder="What languages do you know?"
  selected={[`Python`, `TypeScript`, `Julia`]}
  bind:open
>
  {#snippet selectedItem({ option })}
    <LanguageSnippet {option} />
  {/snippet}
  {#snippet option({ option, selected })}
    <LanguageSnippet {option} style={selected ? `opacity: 0.6` : ``} />
  {/snippet}
  {#snippet expandIcon({ open: expandOpen, disabled })}
    <button {disabled}>
      <Icon icon={expandOpen ? `Collapse` : `Expand`} />
    </button>
  {/snippet}
  {#snippet removeIcon({ option: opt, isRemoveAll })}
    <span style="width: 2ex" title={isRemoveAll ? `Remove all` : `Remove ${opt}`}>✕</span>
  {/snippet}
</MultiSelect>
```

--------------------------------

### Prevent Infinite Loops with Store Binding

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/persistent/+page.md

This example tests and demonstrates the fix for issue #309, ensuring that binding MultiSelect to reactive wrappers like Svelte stores (which clone arrays on assignment) does not cause infinite loops.

```svelte
<script lang="ts">
  import MultiSelect from '$lib'
  import { type Writable, writable } from 'svelte/store'

  // Regression test for issue #309: store subscriptions would cause infinite
  // loops without the values_equal() fix in MultiSelect.svelte
  const options: string[] = [`Red`, `Green`, `Blue`]
  let increment = $state(0)
  let list_store: Writable<string[]> = writable([])

  list_store.subscribe(() => increment++)
</script>

<MultiSelect {options} bind:selected={$list_store} placeholder="Select colors..." />
<p id="store-binding-status">
  Modified: {increment} times
  {#if increment > 50}⚠️ Regression!{:else if increment > 1}✅ Fixed{/if}
</p>
```

--------------------------------

### Controlling Selection Count with `minSelect` and `maxSelect`

Source: https://context7.com/janosh/svelte-multiselect/llms.txt

Demonstrates how to enforce minimum and maximum selection counts using `minSelect` and `maxSelect` props, including custom messages and an `onmaxreached` event handler.

```svelte
<script lang="ts">
  import MultiSelect from 'svelte-multiselect'

  let selected = $state<string[]>([])
  let count    = $derived(selected.length)
</script>

<MultiSelect
  options={['A', 'B', 'C', 'D', 'E']}
  bind:selected
  minSelect={2}
  maxSelect={4}
  maxSelectMsg={(current, max) => `${current} of ${max} chosen`}
  onmaxreached={({ attemptedOption, maxSelect }) =>
    alert(`Limit of ${maxSelect} reached — cannot add "${attemptedOption}"`)}
/>
<p>Chosen: {count}</p>
```

--------------------------------

### Command Palette Component (`CmdPalette`)

Source: https://context7.com/janosh/svelte-multiselect/llms.txt

Utilize the `CmdPalette` component for a command-palette UI triggered by keyboard shortcuts. It integrates with actions defined by label, action function, and an optional icon.

```svelte
<script lang="ts">
  import { CmdPalette } from 'svelte-multiselect'

  const actions = [
    { label: 'Go to Home',       action: () => goto('/'),         icon: '🏠' },
    { label: 'Toggle dark mode', action: () => toggleTheme(),     icon: '🌙' },
    { label: 'Open settings',    action: () => openSettings(),    icon: '⚙️' },
    { label: 'Search docs',      action: () => openSearch(),      icon: '🔍' },
  ]
</script>

<!-- Opens with Ctrl+K (default); press Escape or click outside to close -->
<CmdPalette
  options={actions}
  shortcut="ctrl+k"
  placeholder="Type a command…"
  onselect={({ option }) => option.action()}
/>
```

--------------------------------

### Interactive Example of keepSelectedInDropdown Modes

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/keep-selected/+page.md

This Svelte component allows interactive selection of the `keepSelectedInDropdown` prop. It demonstrates the visual differences between `false` (default), `'plain'`, and `'checkboxes'` modes for selected options in the dropdown. Use this to see how selected items behave in real-time.

```svelte
<script lang="ts">
  import MultiSelect from '$lib'
  import { languages } from '$site/options'

  let selected: string[] = $state(['C', 'Go', 'TypeScript', 'Python'])
  let keepSelectedInDropdown: false | 'plain' | 'checkboxes' = $state('checkboxes')
</script>

{#each [
    [false, 'Default behavior, selected options disappear from dropdown'],
    [
      'plain',
      'Selected options stay visible with left border and background color to differentiate them',
    ],
    ['checkboxes', 'Selected options stay visible and each is prefixed by a checkbox'],
  ] as
  [mode, label]
  (mode)
}
  <label>
    <input type="radio" bind:group={keepSelectedInDropdown} value={mode} /><code
    >keepSelectedInDropdown = {mode}</code> &nbsp; <span>{label}</span>
  </label>
{/each}

<MultiSelect
  id="tech-interactive"
  options={languages}
  bind:selected
  {keepSelectedInDropdown}
  placeholder="Choose languages..."
  closeDropdownOnSelect={false}
/>

<style>
  label {
    display: block;
    margin-block: 1em;
  }
  label > span {
    font-weight: 200;
  }
  label:last-of-type {
    margin-bottom: 2em;
  }
</style>
```

--------------------------------

### Allowing User-Created Options

Source: https://github.com/janosh/svelte-multiselect/blob/main/readme.md

Set `allowUserOptions` to `true` to allow users to add new options to their selection as they type. Use `'append'` to also add the new option to the available `options` list.

```svelte
<!-- Add to selected only -->
<MultiSelect allowUserOptions={true} options={colors} />

<!-- Add to options and selected -->
<MultiSelect allowUserOptions="append" options={colors} />
```

--------------------------------

### Appending User Input to MultiSelect Options

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/allow-user-options/+page.md

Use `allowUserOptions="append"` to allow users to add custom options that are also appended to the dropdown list for future selection. This example customizes the message shown when creating an option and uses a `LanguageSnippet` for rendering options.

```svelte
<script lang="ts">
  import MultiSelect from '$lib'
  import { languages } from '$site/options'
  import { LanguageSnippet } from '$site'

  let selected_append: string[] = $state(['Haskell', 'TypeScript'])
</script>

<MultiSelect
  options={languages}
  allowUserOptions="append"
  bind:selected={selected_append}
  createOptionMsg={({ searchText, options }) =>
  `Add '${searchText}' (${options.length} languages available)`}
>
  {#snippet children({ option })}
    <LanguageSnippet {option} />
  {/snippet}
</MultiSelect>

<p style="margin-top: 0.5em">Selected: {selected_append.join(', ')}</p>
```

--------------------------------

### Object Options with Custom Display

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/infinite-scroll/+page.md

Demonstrates how to use object options with a custom display snippet to render complex data, such as language objects with their release year.

```APIDOC
## Object Options with Custom Display

Use object options with custom snippets:

```svelte
<script lang="ts">
  import MultiSelect from '$lib'
  import type { LoadOptionsParams, LoadOptionsResult, ObjectOption } from '$lib/types'

  interface Language extends ObjectOption {
    year: number
  }

  const all_languages: Language[] = [
    { label: `JavaScript`, year: 1995 },
    { label: `TypeScript`, year: 2012 },
    { label: `Python`, year: 1991 },
    { label: `Rust`, year: 2010 },
    { label: `Go`, year: 2009 },
    { label: `Java`, year: 1995 },
    { label: `C++`, year: 1985 },
    { label: `C#`, year: 2000 },
    { label: `Ruby`, year: 1995 },
    { label: `Swift`, year: 2014 },
  ]

  async function load_options(
    { search, offset, limit }: LoadOptionsParams,
  ): Promise<LoadOptionsResult<Language>> {
    await new Promise((resolve) => setTimeout(resolve, 200))

    const filtered = search
      ? all_languages.filter((lang) =>
        lang.label.toLowerCase().includes(search.toLowerCase())
      )
      : all_languages

    return {
      options: filtered.slice(offset, offset + limit),
      hasMore: offset + limit < filtered.length,
    }
  }
</script>

<MultiSelect loadOptions={load_options} placeholder="Search languages...">
  {#snippet children({ option })}
    <span>{option.label} <small style="opacity: 0.6">({option.year})</small></span>
  {/snippet}
</MultiSelect>
```
```

--------------------------------

### Pasting Multiple Values into MultiSelect

Source: https://github.com/janosh/svelte-multiselect/blob/main/src/routes/(demos)/allow-user-options/+page.md

The `parse_paste` prop allows users to paste comma or newline-separated text, which is then split into multiple options. This example demonstrates parsing emails, multi-word values, and mixed formats, with event logging for created and removed options. Custom logic is included to reject options shorter than 3 characters.

```svelte
<script lang="ts">
  import MultiSelect, { CopyButton } from '$lib'

  let selected: string[] = $state([])
  let log: string[] = $state([])

  const snippets = [
    { label: `Comma-separated emails`, text: `alice@example.com, bob@test.org, carol@mail.net` },
    { label: `Multi-word values`, text: `New York, Los Angeles, San Francisco` },
    { label: `Newline-separated`, text: `Red\nGreen\nBlue\nYellow` },
    { label: `Mixed commas & newlines`, text: `one, two\nthree, four` },
  ]
</script>

<div style="display: flex; flex-direction: column; gap: 0.4em; margin-bottom: 1em">
  {#each snippets as { label, text }}
    <div style="display: flex; align-items: center; gap: 0.5em">
      <CopyButton
        content={text}
        style="padding: 0.3em 0.7em; border-radius: 4px; border: 1px solid var(--sms-border, lightgray); background: var(--sms-options-bg, white); cursor: pointer; font-size: 0.85em; white-space: nowrap"
        labels={{ 
          ready: { icon: `Copy`, text: label },
          success: { icon: `Check`, text: `Copied!` },
          error: { icon: `Alert`, text: `Failed` },
        }}
      />
      <code style="font-size: 0.85em; opacity: 0.7">{text}</code>
    </div>
  {/each}
</div>

<MultiSelect
  allowUserOptions="append"
  bind:selected
  noMatchingOptionsMsg=""
  createOptionMsg={null}
  parse_paste={(text) => text.split(/[,
]+/).map((s) => s.trim()).filter(Boolean)}
  oncreate={({ option }) => {
    if (String(option).length < 3) {
      log = [...log, `✗ rejected "${option}" (too short)`]
      return false
    }
    log = [...log, `+ ${option}`]
  }}
  onremove={({ option }) => log = [...log, `- ${option}`]}
/>

<p style="margin-top: 0.5em">
  Selected ({selected.length}): {selected.join(', ') || 'none'}
</p>

{#if log.length > 0}
  <details open style="margin-top: 0.5em">
    <summary>Event log ({log.length})</summary>
    <pre style="max-height: 8em; overflow: auto; font-size: 0.85em"><code>{log.join('\n')}</code></pre>
  </details>
{/if}
```