Solid List Utility

Common errors

• TypeError: createList is not a function

  cause Attempting to import `createList` using CommonJS `require()` syntax in an environment that expects ESM, or incorrect import path.
  fix Ensure you are using ES module import syntax: `import { createList } from 'solid-list'` and that your build setup supports ESM.

• Keyboard navigation does not work or active item jumps erratically.

  cause The `onKeyDown` handler from `createList` is not attached to the correct element, or the `items` accessor is not reactive, or list items lack unique, stable `id`s.
  fix Attach `onKeyDown` to the parent container of your list or the input that triggers list interaction. Verify that the `items` option passed to `createList` is a reactive signal/memo returning unique IDs, and that your rendered list items have consistent `id` attributes that match these IDs.

Warnings

• gotcha The documentation for the `handleTab` option in the README is contradictory. One line states `handleTab: false, // default = true`. It is safer to explicitly set `handleTab` to your desired behavior (`true` or `false`) rather than relying on an ambiguous default.
  Fix: Always explicitly specify `handleTab: true` or `handleTab: false` in the `createList` options to ensure consistent behavior.
• breaking `solid-list` is currently in a pre-1.0 version (0.3.0). As such, breaking changes may be introduced in minor releases without strict adherence to semantic versioning until a stable 1.0 release. Always review changelogs when upgrading.
  Fix: Consult the project's GitHub releases and changelog before upgrading minor versions to identify potential breaking changes and necessary migration steps.
• gotcha The `items` option for `createList` must be a function that returns an array of unique identifiers for your list items (e.g., `() => results().map(result => result.id)`). If the accessor is not reactive or does not return stable IDs, keyboard navigation or active state management might behave unpredictably.
  Fix: Ensure the `items` option is a reactive accessor (a SolidJS signal or memo) that consistently returns an array of unique and stable IDs for your list elements.

Install

• npm install solid-list npm
• yarn add solid-list yarn
• pnpm add solid-list pnpm

Imports

• createList
  wrong:

  const createList = require('solid-list')

  correct:

  import { createList } from 'solid-list'

  solid-list is an ESM-first package. Use ES module import syntax. `createList` is a SolidJS factory function.

Quickstart

This example demonstrates how to create a simple, keyboard-navigable search results list using `createList`. It includes basic reactivity for filtering results and correct event handling for keyboard and mouse interaction, along with ARIA attributes for accessibility.

import { createSignal, For } from 'solid-js';
import { createList } from 'solid-list';

const Search = () => {
  const [results, setResults] = createSignal([
    { id: '1', name: 'Apple', href: '/products/apple' },
    { id: '2', name: 'Banana', href: '/products/banana' },
    { id: '3', name: 'Cherry', href: '/products/cherry' },
    { id: '4', name: 'Date', href: '/products/date' }
  ]);

  const { active, setActive, onKeyDown } = createList({
    items: () => results().map(result => result.id), // required, should be a reactive accessor
    initialActive: null, // default, T | null
    orientation: 'vertical', // default, 'vertical' | 'horizontal'
    loop: true, // default
    textDirection: 'ltr', // default, 'ltr' | 'rtl'
    handleTab: true, // default
    vimMode: false, // default
    onActiveChange: (newActiveId) => {
      console.log('Active item changed to:', newActiveId);
      // Optionally, scroll into view or navigate
    }
  });

  const handleInput = (e) => {
    const query = e.target.value.toLowerCase();
    setResults([
      { id: '1', name: 'Apple', href: '/products/apple' },
      { id: '2', name: 'Banana', href: '/products/banana' },
      { id: '3', name: 'Cherry', href: '/products/cherry' },
      { id: '4', name: 'Date', href: '/products/date' }
    ].filter(item => item.name.toLowerCase().includes(query)));
  };

  return (
    <div class="search-container">
      <input
        type="text"
        placeholder="Search fruits..."
        onInput={handleInput}
        onKeyDown={onKeyDown}
        aria-controls="search-results-list"
        aria-expanded={results().length > 0}
        role="combobox"
      />
      {results().length > 0 && (
        <ul id="search-results-list" role="listbox">
          <For each={results()}>
            {(item) => (
              <li
                id={`item-${item.id}`}
                role="option"
                aria-selected={active() === item.id}
                tabIndex={active() === item.id ? 0 : -1}
                onClick={() => setActive(item.id)}
                onMouseEnter={() => setActive(item.id)} // for mouse navigation
              >
                <a href={item.href} tabIndex={-1}>{item.name}</a>
              </li>
            )}
          </For>
        </ul>
      )}
    </div>
  );
};