List Component

Variants

variant=primary

variant=success

variant=danger

A variant re-points --ui-accent (via .ui-accent), so the hover / keyboard-cursor / selected tints pick up that colour; the frame stays neutral. Same selection across all three so you can compare the tint.

Sizes

size=sm

size=md

size=lg

size scales the option text/row height.

Basic

List

Selected Value

import { List } from 'svelte-ui';

const basicOptions = [
  { value: 'option1', label: 'Option 1' },
  { value: 'option2', label: 'Option 2' },
  { value: 'option3', label: 'Option 3' },
  { value: 'option4', label: 'Option 4' },
  { value: 'option5', label: 'Option 5' },
  { value: 'option6', label: 'Option 6' }
];

let selectedItem = $state('');

<List
  options={basicOptions}
  maxVisibleItems={3}
  bind:value={selectedItem}
  class="w-full"
/>

Empty

Empty with Custom Text

Behavior

import { List } from 'svelte-ui';

let selectedItem = $state('');

<List 
  options={[]}
  emptyText="<Empty>"
  bind:value={selectedItem}
  class="w-full"
/>

// Empty lists maintain the minimum height (32px)
// The emptyText prop customizes what's shown when no options exist

Auto-Height

Without maxVisibleItems

Selected Value

import { List } from 'svelte-ui';

const basicOptions = [
  { value: 'option1', label: 'Option 1' },
  { value: 'option2', label: 'Option 2' },
  { value: 'option3', label: 'Option 3' },
  { value: 'option4', label: 'Option 4' },
  { value: 'option5', label: 'Option 5' },
  { value: 'option6', label: 'Option 6' }
];

let selectedItem = $state('');

// When maxVisibleItems is not set, the list grows to show all items
<List 
  options={basicOptions}
  bind:value={selectedItem}
  class="w-full"
/>

// This will display all 6 items without scrolling
// The list height automatically adjusts to fit all content

Custom Item Rendering

Custom Snippets

Selected Value

import { List } from 'svelte-ui';

const fruitOptions = [
  { value: 'apple', label: 'Apple', emoji: '🍎', description: 'Crisp and sweet' },
  { value: 'banana', label: 'Banana', emoji: '🍌', description: 'Rich in potassium' },
  { value: 'orange', label: 'Orange', emoji: '🍊', description: 'High in vitamin C' },
  { value: 'grape', label: 'Grape', emoji: '🍇', description: 'Great for snacking' },
  { value: 'strawberry', label: 'Strawberry', emoji: '🍓', description: 'Sweet and juicy' },
  { value: 'pineapple', label: 'Pineapple', emoji: '🍍', description: 'Tropical and tangy' },
  { value: 'watermelon', label: 'Watermelon', emoji: '🍉', description: 'Refreshing summer fruit' },
  { value: 'cherry', label: 'Cherry', emoji: '🍒', description: 'Small but flavorful' }
];

let selectedItem = $state('');

<List
  options={fruitOptions}
  maxVisibleItems={5}
  bind:value={selectedItem}
  class="w-full"
>
  {#snippet itemSnippet(option, index, isSelected, isFocused)}
    <div class="flex items-center gap-3 px-3 py-2 w-full">
      <span class="text-2xl">{option.emoji}</span>
      <div class="flex-1">
        <div class="font-medium">{option.label}</div>
        <div class="text-sm [color:color-mix(in_srgb,var(--ui-color-text)_60%,transparent)]">{option.description}</div>
      </div>
    </div>
  {/snippet}
</List>

Multi-Select

Multi-Select List

Selected Values

Multi-Select with Custom Items

Use Space to toggle selection

import { List } from 'svelte-ui';

const basicOptions = [
  { value: 'option1', label: 'Option 1' },
  { value: 'option2', label: 'Option 2' },
  { value: 'option3', label: 'Option 3' },
  { value: 'option4', label: 'Option 4' },
  { value: 'option5', label: 'Option 5' },
  { value: 'option6', label: 'Option 6' },
  { value: 'option7', label: 'Option 7' },
  { value: 'option8', label: 'Option 8' }
];

const fruitOptions = [
  { value: 'apple', label: 'Apple', emoji: '🍎', description: 'Crisp and sweet' },
  { value: 'banana', label: 'Banana', emoji: '🍌', description: 'Rich in potassium' },
  { value: 'orange', label: 'Orange', emoji: '🍊', description: 'High in vitamin C' },
  { value: 'grape', label: 'Grape', emoji: '🍇', description: 'Great for snacking' },
  { value: 'strawberry', label: 'Strawberry', emoji: '🍓', description: 'Sweet and juicy' },
  { value: 'pineapple', label: 'Pineapple', emoji: '🍍', description: 'Tropical and tangy' },
  { value: 'watermelon', label: 'Watermelon', emoji: '🍉', description: 'Refreshing summer fruit' },
  { value: 'cherry', label: 'Cherry', emoji: '🍒', description: 'Small but flavorful' }
];

let multiSelectedItems = $state([]);
let multiSelectedFruits = $state([]);

// Basic Multi-Select
<List
  options={basicOptions}
  maxVisibleItems={4}
  multiSelect={true}
  bind:value={multiSelectedItems}
  class="w-full"
/>

// Multi-Select with Custom Rendering
<List
  options={fruitOptions}
  maxVisibleItems={5}
  multiSelect={true}
  bind:value={multiSelectedFruits}
  class="w-full"
>
  {#snippet itemSnippet(option, index, isSelected, isFocused)}
    <div class="flex items-center gap-3 px-2 py-2 w-full">
      <span class="text-2xl">{option.emoji}</span>
      <div class="flex-1">
        <div class="font-medium">{option.label}</div>
        <div class="text-sm [color:color-mix(in_srgb,var(--ui-color-text)_60%,transparent)]">{option.description}</div>
      </div>
      {#if isSelected}
        <span class="text-sm text-green-600 font-medium">✓</span>
      {/if}
    </div>
  {/snippet}
</List>

Checkboxes

Static API Data

Load data from an API once on component mount with optional static filtering.

List (API Data)

Selected Value

All Countries

Data loaded automatically on mount

North America Only (Static Filter)

Filtered to North America using static searchTerm

import { List } from 'svelte-ui';

let selectedItem = $state('');

// Example 1: All Countries
<List 
  options={[]}
  url="/api/countries"
  transform={(data) => data.map((country: any) => ({
    value: country.countryCode,
    label: `${country.countryName} (${country.region})`
  }))}
  maxVisibleItems={6}
  bind:value={selectedItem}
/>

// Example 2: North America Only (Static Filter)
<List 
  options={[]}
  url="/api/countries"
  searchParam="region"
  searchTerm="North America"
  transform={(data) => data.map((country: any) => ({
    value: country.countryCode,
    label: country.countryName
  }))}
  maxVisibleItems={5}
  bind:value={selectedItem}
/>

// How it works:
// 1. When searchParam is provided with a static searchTerm, it acts as a filter
// 2. API is called once with the query parameter: ?region=North America
// 3. No dynamic search - the searchTerm is fixed
// 4. Perfect for pre-filtered lists without user input
// 5. Use bind:searchTerm for dynamic search-as-you-type functionality

Features

Key Features:

• Keyboard Navigation: Arrow keys navigate, Space toggles selection, Enter submits form
• Multi-Select Support: Select multiple items with highlighting or checkboxes
• Checkbox Mode: `showCheckboxes=true` enables visual checkboxes with no selection highlighting
• Custom Rendering: Use snippets to customize how items are displayed
• Auto-scroll: Focused item automatically scrolls into view
• Custom Scrollbar: Styled scrollbar with drag support
• API Integration: Built-in support for fetching data from APIs
• Search Support: Optional search-as-you-type functionality
• Transform Function: Map API responses to the required format
• Configurable Height: Set max visible items and item height
• Selection Callback: Get notified when items are selected
• Loading States: Built-in loading indicators and error handling

Use Cases

Perfect for:

• Command Palettes: Search and select commands or actions
• Data Browsers: Browse through large datasets with scrolling
• Search Results: Display search results with rich formatting
• Menu Lists: Navigation menus with custom styling
• Autocomplete: Type-ahead suggestions with API integration
• File Browsers: Browse files and folders with metadata
• User Lists: Display users with avatars and details
• Inside Select: Will be used internally by Select component for dropdown lists

List Component

Variants

Sizes

Basic

List

Selected Value

Empty

Empty with Custom Text

Behavior

Auto-Height

Without maxVisibleItems

Selected Value

Custom Item Rendering

Custom Snippets

Selected Value

Multi-Select

Multi-Select List

Selected Values

Multi-Select with Custom Items

Checkboxes

List with Checkboxes

Selected Values

Pre-selected with Custom Rendering

Static API Data

List (API Data)

Selected Value

All Countries

North America Only (Static Filter)

Features

Key Features:

Use Cases

Perfect for: