react-generic-list

A generic, accessible, and performant list component for React 19 — written in TypeScript with full type safety, keyboard navigation, selection management, and optional virtualization built in.

Features

• Generic & type-safe — works with any data shape via TypeScript generics
• Accessible by default — semantic ul/li with ARIA roles, labels, and keyboard navigation (WAI-ARIA listbox/list patterns)
• Flexible rendering — custom render functions, custom wrappers, and configurable item elements
• Selection management — controlled or uncontrolled selection out of the box
• Keyboard navigation — Arrow keys, Home/End, Enter/Space, Tab, with optional looping
• Scroll management — auto-scrolls to selected or focused items
• Virtualization hook — handles large lists (> 100 items by default) automatically
• Composable hooks — useListSelection, useListKeyboard, useListScroll are all individually exported
• Dual output mode — semantic (ul/li) or generic (div/div)
• Zero runtime dependencies — peer-deps are only react and react-dom
• ESM + UMD — ships both module formats with TypeScript declarations

Installation

npm install react-generic-list
# or
yarn add react-generic-list
# or
pnpm add react-generic-list

Peer dependencies (install separately if not already present):

npm install react@^19.0.0 react-dom@^19.0.0

Quick Start

import { List } from "react-generic-list";

type User = { id: number; name: string; email: string };

const users: User[] = [
  { id: 1, name: "Alice", email: "[email protected]" },
  { id: 2, name: "Bob", email: "[email protected]" },
];

export default function App() {
  return (
    <List
      items={users}
      keyExtractor={(user) => user.id}
      render={(user) => (
        <span>
          {user.name} — {user.email}
        </span>
      )}
    />
  );
}

Props (ListProps<T>)

Core

| Prop | Type | Required | Description | | -------------- | ---------------------------------------------- | -------- | ----------------------------- | | items | T[] | ✅ | Array of items to render | | keyExtractor | (item: T, index: number) => string \| number | ✅ | Unique key for each item | | render | (item: T, index: number) => ReactNode | ✅ | Render function for each item |

Mode & Custom Wrappers

| Prop | Type | Default | Description | | ------------- | ------------------------- | ------------ | --------------------------------------------------------------- | | mode | "semantic" \| "generic" | "semantic" | "semantic" renders ul/li; "generic" renders div/div | | wrapper | ElementType | — | Overrides the container element entirely | | itemWrapper | ElementType | — | Overrides the item element entirely |

Styling

| Prop | Type | Default | Description | | ---------------- | ---------------------------------------------------------------------------- | ------- | ----------------------------------------------------- | | className | string | — | CSS class for the container | | style | CSSProperties | — | Inline styles for the container | | id | string | — | id attribute on the container | | childProps | ComponentProps<"li"> \| ((item: T, index: number) => ComponentProps<"li">) | — | Static or dynamic props applied to every item element | | preserveStyles | boolean | true | Removes default list-style-type in semantic mode |

Selection

| Prop | Type | Default | Description | | -------------- | ---------------------------------- | ------- | --------------------------------------------------------------------------- | | onItemSelect | (item: T, index: number) => void | — | Callback when an item is selected. Providing this makes the list selectable | | selectedItem | T \| null | — | Controlled selected item |

State

| Prop | Type | Default | Description | | ------------------ | ----------- | ----------------------- | ----------------------------------- | | loading | boolean | false | Shows loading state | | loadingComponent | ReactNode | "Loading..." | Custom loading UI | | emptyMessage | string | "No items to display" | Message shown when items is empty | | emptyComponent | ReactNode | — | Custom empty state UI |

Keyboard Navigation

| Prop | Type | Default | Description | | ------------------------ | --------- | ------- | ------------------------------------------ | | keyboardNavigation | boolean | true | Enable/disable keyboard navigation | | loopNavigation | boolean | true | Whether arrow keys wrap around at the ends | | scrollIntoViewOnSelect | boolean | true | Auto-scroll to selected item |

Accessibility

| Prop | Type | Default | Description | | ---------------- | -------- | -------- | ----------------------------------- | | ariaLabel | string | "list" | aria-label for the container | | ariaLabelledBy | string | — | aria-labelledby for the container |

Examples

Controlled selection

const [selected, setSelected] = useState<User | null>(null);

<List
  items={users}
  keyExtractor={(u) => u.id}
  render={(u) => <span>{u.name}</span>}
  selectedItem={selected}
  onItemSelect={(user) => setSelected(user)}
/>;

Custom loading & empty states

<List
  items={[]}
  keyExtractor={(u) => u.id}
  render={(u) => <span>{u.name}</span>}
  loading={isLoading}
  loadingComponent={<Spinner />}
  emptyComponent={<p>No users found.</p>}
/>

Generic (non-semantic) mode with custom wrapper

<List
  items={items}
  keyExtractor={(i) => i.id}
  render={(i) => <Card {...i} />}
  mode="generic"
  className="card-grid"
/>

Per-item dynamic props

<List
  items={items}
  keyExtractor={(i) => i.id}
  render={(i) => <span>{i.label}</span>}
  childProps={(item, index) => ({
    className: item.isActive ? "active" : "",
    "data-index": index,
  })}
/>

Disable keyboard navigation

<List
  items={items}
  keyExtractor={(i) => i.id}
  render={(i) => <span>{i.name}</span>}
  keyboardNavigation={false}
/>

Exported Hooks

The package exports three standalone hooks for building custom list UIs.

useListSelection<T>

Manages controlled/uncontrolled item selection.

import { useListSelection } from "react-generic-list";

const { selectedItem, isSelected, handleItemSelect, clearSelection } =
  useListSelection({
    items,
    keyExtractor: (item) => item.id,
    onItemSelect: (item, index) => console.log(item),
    selectedItem: externalValue, // optional, for controlled usage
  });

Returns:

| Key | Type | Description | | ------------------ | -------------------------- | ------------------------------------- | | selectedItem | T \| null | Currently selected item | | selectedIndex | number | Index of selected item (-1 if none) | | isSelected | (item, index) => boolean | Check if an item is selected | | handleItemSelect | (item, index) => void | Select an item | | clearSelection | () => void | Clear current selection |

useListKeyboard<T>

Manages keyboard-driven focus and selection within a list.

import { useListKeyboard } from "react-generic-list";

const {
  focusedIndex,
  handleKeyDown,
  handleItemKeyDown,
  handleItemFocus,
  resetFocus,
} = useListKeyboard({
  items,
  onItemSelect: (item, index) => select(item),
  enabled: true,
  loopNavigation: true,
});

Supported keys: ArrowDown, ArrowUp, Home, End, Enter, Space, Tab

Returns:

| Key | Type | Description | | ------------------- | ---------------------------------------- | ---------------------------- | | focusedIndex | number | Currently focused item index | | setFocusedIndex | (index) => void | Programmatically set focus | | handleKeyDown | KeyboardEventHandler<HTMLUListElement> | Attach to the container | | handleItemKeyDown | (e, item, index) => void | Attach to individual items | | handleItemFocus | (index) => void | Called on item focus | | resetFocus | () => void | Reset focused index to -1 |

useListScroll

Scrolls the list container to a specific item index.

import { useListScroll } from "react-generic-list";

const { containerRef, scrollToIndex, scrollToSelected } = useListScroll({
  scrollIntoViewOnFocus: true,
  scrollBehavior: "smooth",
});

Returns:

| Key | Type | Description | | ------------------ | --------------------------------- | ----------------------------------------- | | containerRef | RefObject<HTMLUListElement> | Attach to the list container | | scrollToIndex | (index: number) => void | Scroll to a specific index | | scrollToSelected | (selectedIndex: number) => void | Scroll to selected index (no-op if < 0) |

Virtualization (Internal)

The library includes a useListVirtualization hook (internal, not exported) that automatically activates when the list contains more than 100 items. It uses ResizeObserver and scroll events to compute a visible window, renders only the visible items plus an overscan buffer, and maintains correct total height for the scrollbar.

If you need direct access for advanced use cases, copy the hook from src/hooks/useListVirtualization.ts.

Keyboard Navigation Reference

| Key | Action | | ----------------- | --------------------------------------------------------- | | ↓ ArrowDown | Move focus to next item (wraps with loopNavigation) | | ↑ ArrowUp | Move focus to previous item (wraps with loopNavigation) | | Home | Move focus to first item | | End | Move focus to last item | | Enter / Space | Select focused item | | Tab | Exit list, reset focus |

Accessibility

• Container renders as <ul role="listbox"> when onItemSelect is provided, otherwise <ul role="list">
• Each item gets role="option" (selectable) or role="listitem"
• Selected items receive aria-selected="true" and aria-current="true"
• Items are auto-labelled as "<ariaLabel> item <n>"
• In generic mode, ARIA roles are intentionally omitted to avoid incorrect semantics

TypeScript

All props and hook signatures are fully typed. The List component is generic over your item type T — no casting needed:

// TypeScript infers T as User automatically
<List<User>
  items={users}
  keyExtractor={(u) => u.id}
  render={(u) => <span>{u.name}</span>}
/>

License

MIT © Usama Imran