svelte-widgets

If your API uses opaque cursors (like Stripe or GitHub GraphQL) instead of offset/limit, you can manage the cursor within a closure.

Important: To prevent the component from resetting the loaded batch, ensure you pass a stable function reference to loadOptions. When offset === 0, it indicates a fresh search or a reopened dropdown, and you should reset your cursor.

function make_load_options() {
  let cursor: string | null = null

  return async ({ search, offset, limit, signal }: LoadOptionsParams) => {
    // Reset cursor on new search or dropdown open
    if (offset === 0) cursor = null

    const params = new URLSearchParams({ q: search, limit: `${limit}` })
    if (cursor) params.set(`cursor`, cursor)

    const response = await fetch(`/api/items?${params}`, { signal })
    const { items, next_cursor } = await response.json()
    
    cursor = next_cursor
    return { options: items, hasMore: Boolean(next_cursor) }
  }
}

// In your Svelte component:
const load_options = make_load_options()
// Pass the stable reference
<MultiSelect loadOptions={load_options} />

The MultiSelect component includes built-in selection history by default, allowing users to undo and redo changes.

• Enable/Disable: Use the history prop.
  • true (default): Enables history with a maximum of 50 entries.
  • number: Sets a custom maximum number of history entries.
  • false or 0: Disables history entirely.
• Keyboard Shortcuts: By default, users can use Ctrl+Z / Cmd+Z to undo and Ctrl+Shift+Z / Cmd+Shift+Z to redo (platform-aware). You can override these using the shortcuts prop.
• Behavior:
  • History tracks all changes to the selected array, including updates made via props from outside the component.
  • Performing a new selection after an undo operation will clear the redo stack.
  • Undo/redo functionality is automatically disabled when the component is in a disabled state.

<MultiSelect history={50} />
<!-- or to disable -->
<MultiSelect history={false} />
<!-- or to customize shortcuts -->
<MultiSelect history={true} shortcuts={{ undo: 'alt+z', redo: 'alt+shift+z' }} />

The FullscreenButton component and the headless sync_fullscreen function maintain a two-way synchronization between a bindable fullscreen flag and the browser's actual fullscreen state. The fullscreen flag acts as the single source of truth: whether the user clicks the button, manually flips the flag in code, or presses <kbd>Esc</kbd>, the flag and the browser state will stay in agreement.

Key Behavior:

• Isolation: Synchronization is keyed to a specific wrapper element. If you have multiple independent wrappers on a page, each with its own flag, toggling fullscreen for one will not affect the flags of the others. This prevents the issue where every component on a page tries to trigger requestFullscreen simultaneously.
• Background Painting: To prevent a black screen when entering fullscreen, the library automatically paints the page background onto a CSS variable. By default, this is --fullscreen-bg, but you can customize it using the bg_css_var option.

<FullscreenButton 
  wrapper={wrapper_element} 
  bind:fullscreen={fullscreen_flag} 
  bg_css_var="--custom-bg-var" 
/>

By default, ButtonGroup operates in single-select mode (multiple={false}). It behaves as a radiogroup of role="radio" buttons.

Key behaviors:

• Keyboard Navigation: One tab stop for the whole group. Arrow keys walk through options (wrapping at ends, skipping disabled ones). Home and End jump to the start/end.
• Sorting: If sort_order is provided (not null), a sort arrow is rendered. You can style this arrow using sort_button_props (note: host style does not reach this button as it sits outside the radiogroup).
• Selection: Use bind:selected to manage the single active value.

<script lang="ts">
  import ButtonGroup, { type ButtonGroupOption } from '$lib/ButtonGroup.svelte'

  const options: ButtonGroupOption[] = [
    { value: 'commits', label: 'commits', tooltip: 'Total commits' },
    { value: 'stars', label: 'stars' },
  ]
  let sort_by = $state('commits')
  let sort_order = $state<'asc' | 'desc'>('desc')
</script>

<ButtonGroup
  {options}
  bind:selected={sort_by}
  bind:sort_order
  label="Sort projects by"
/>

To enable multi-select, add the multiple prop. This changes the semantics from a radio group to a group of independent toggle buttons with aria-pressed.

Key behaviors:

• Selection: bind:selected expects an array of values.
• Customization: Use the option snippet to replace a button's internal content and the option_suffix snippet to add content alongside the label.
• Snippets:
  • option({ option, selected }): Controls the button's inner content.
  • option_suffix({ option }): Renders a sibling element wrapped in a .option span. This is useful for non-interactive elements like counts. When used, --btn-group-option-btn-padding-right (default 0.5ex) is applied to the button to make room for the suffix.

<script lang="ts">
  import ButtonGroup from '$lib/ButtonGroup.svelte'

  const tags = { svelte: 'Svelte', kit: 'SvelteKit' }
  let active = $state(['svelte'])
</script>

<ButtonGroup
  options={tags}
  multiple
  bind:selected={active}
  label="Filter by tag"
>
  {#snippet option({ option: opt, selected })}
    {opt.label} {selected ? '×' : '+'}
  {/snippet}
  {#snippet option_suffix({ option: opt })}
    <span>Count: 12</span>
  {/snippet}
</ButtonGroup>