List

A scrollable list container with keyboard navigation, highlight, selection and scroll-bottom callbacks

Installation

$npx litefy@latest add list
$pnpm dlx litefy@latest add list
$yarn dlx litefy@latest add list
$bun --bun litefy@latest add list

Usage

A scroll container driven by items, with rows rendered via renderItem; pair with usePagination when paging is needed.

Design reviewtodo
API integrationin-progress
Write testsin-progress
Release notesdone
Deploytodo
Retrospectivetodo

"use client";import { List } from "@/ui";interface Task {  id: number;  title: string;  status: string;}const tasks: Task[] = [  { id: 1, title: "Design review", status: "todo" },  { id: 2, title: "API integration", status: "in-progress" },  { id: 3, title: "Write tests", status: "in-progress" },  { id: 4, title: "Release notes", status: "done" },  { id: 5, title: "Deploy", status: "todo" },  { id: 6, title: "Retrospective", status: "todo" },];export default function ListBasicDemo() {  return (    <List      className="h-40 w-full max-w-md border"      items={tasks}      getKey={(task) => task.id}      empty={<div className="px-3 py-4 text-center text-muted-foreground">No data</div>}      classNames={{ item: "flex items-center gap-2" }}      renderItem={(task) => (        <>          <span className="flex-1 truncate">{task.title}</span>          <span className="text-muted-foreground">{task.status}</span>        </>      )}    />  );}

Ordered List

Order renders the same list as an <ol> with decimal numbering — for sequences where order is part of the meaning.

Freeze the release branchAlice
Run the regression suiteBob
Write release notesCarol
Tag and deployAlice
Announce in the changelogBob

"use client";import { Order } from "@/ui";interface Step {  id: number;  title: string;  owner: string;}const steps: Step[] = [  { id: 1, title: "Freeze the release branch", owner: "Alice" },  { id: 2, title: "Run the regression suite", owner: "Bob" },  { id: 3, title: "Write release notes", owner: "Carol" },  { id: 4, title: "Tag and deploy", owner: "Alice" },  { id: 5, title: "Announce in the changelog", owner: "Bob" },];export default function ListOrderDemo() {  return (    <Order      className="h-40 w-full max-w-md border"      items={steps}      getKey={(step) => step.id}      empty={<div className="px-3 py-4 text-center text-muted-foreground">No steps</div>}      renderItem={(step) => (        <div className="flex items-center gap-2">          <span className="flex-1 truncate">{step.title}</span>          <span className="text-muted-foreground">{step.owner}</span>        </div>      )}    />  );}

Numbers render via ::marker, which requires rows to keep display: list-item — display utilities on classNames.item (e.g. flex) remove them, so lay out row content inside renderItem instead.

Grouping

Provide getGroup / renderGroupHeader to render group headers — plain rows that keyboard navigation never highlights or selects.

Engineering

AliceEngineering
BobEngineering

Design

CarolDesign
DavidDesign

Marketing

ErinMarketing

Selected: - — group headers are not navigable or selectable

"use client";import { useState } from "react";import { List } from "@/ui";const contacts = [  { name: "Alice", role: "Engineering" },  { name: "Bob", role: "Engineering" },  { name: "Carol", role: "Design" },  { name: "David", role: "Design" },  { name: "Erin", role: "Marketing" },];export default function Demo() {  const [selected, setSelected] = useState<string | null>(null);  return (    <div className="flex flex-col gap-3 w-xs">      <List        className="h-64 rounded-md border"        items={contacts}        getKey={(contact) => contact.name}        getGroup={(contact) => contact.role}        renderGroupHeader={(group) => group}        classNames={{ item: "flex items-center gap-2" }}        onSelect={(contact) => setSelected(contact.name)}        renderItem={(contact) => (          <>            <span className="flex-1 truncate">{contact.name}</span>            <span className="text-muted-foreground">{contact.role}</span>          </>        )}      />      <p className="text-sm text-muted-foreground wrap-break-word">        Selected: {selected ?? "-"} — group headers are not navigable or selectable      </p>    </div>  );}

API Reference

High-level Components

A scrollable, keyboard-navigable list; sizing is fully controlled by the consumer (e.g. h-40 rounded-md border).

Prop	Type	Default	Description
`items`	`T[]`	-	Data array to render
`renderItem`	`(item: T, index: number) => ReactNode`	-	Row content renderer
`getKey`	`(item: T, index: number) => Key`	-	Row key extractor; defaults to the index
`empty`	`React.ReactNode`	-	Rendered when `items` is empty
`highlightIndex`	`number \| null`	-	Controlled highlight index; omit for internal keyboard navigation
`onHighlightChange`	`(index: number \| null) => void`	-	Fired when the highlight changes
`getGroup`	`(item: T, index: number) => string`	-	Group label extractor; grouping is enabled only when both `getGroup` and `renderGroupHeader` are provided
`renderGroupHeader`	`(groupName: string) => ReactNode`	-	Group header renderer; grouping is enabled only when both `getGroup` and `renderGroupHeader` are provided
`onSelect`	`(item: T, index: number) => void`	-	Fired when a row is clicked or confirmed with `Enter` during keyboard navigation
`onScrollBottom`	`() => void`	-	Fired when the list is scrolled to within 16px of the bottom, for load-more scenarios
`onItemMouseMove`	`(item: T, index: number) => void`	-	Fired as the pointer moves over a row — pass it `setHighlightIndex` to let hover and keyboard share one highlight
`ref`	`React.Ref<HTMLUListElement \| HTMLDivElement>`	-	Ref to the root element — a `ul` in flat mode, a `div` when grouped, e.g. to move focus into the list
`className`	`ClassNameValue`	-	Custom class for the root
`style`	`React.CSSProperties`	-	Custom inline style for the root
`classNames`	`{ item?: ClassNameValue; groupHeader?: ClassNameValue }`	-	Custom classes for the rows and group headers
`styles`	`{ item?: React.CSSProperties; groupHeader?: React.CSSProperties }`	-	Custom inline styles for the rows and group headers

No built-in dividers or edge shadows — add divide-y classes and pair with ScrollShadow as needed.

An ordered-list variant that renders the root as an <ol> with decimal numbering (list-decimal pl-6). It accepts all List props except the grouping API (getGroup / renderGroupHeader), and its ref is React.Ref<HTMLOListElement>.

Prop	Type	Default	Description
`items`	`T[]`	-	Data array to render
`renderItem`	`(item: T, index: number) => ReactNode`	-	Row content renderer
`getKey`	`(item: T, index: number) => Key`	-	Row key extractor; defaults to the index
`empty`	`React.ReactNode`	-	Rendered when `items` is empty
`highlightIndex`	`number \| null`	-	Controlled highlight index; omit for internal keyboard navigation
`onHighlightChange`	`(index: number \| null) => void`	-	Fired when the highlight changes
`onSelect`	`(item: T, index: number) => void`	-	Fired when a row is clicked or confirmed with `Enter` during keyboard navigation
`onScrollBottom`	`() => void`	-	Fired when the list is scrolled to within 16px of the bottom, for load-more scenarios
`onItemMouseMove`	`(item: T, index: number) => void`	-	Fired as the pointer moves over a row
`ref`	`React.Ref<HTMLOListElement>`	-	Ref to the root `<ol>` element
`className`	`ClassNameValue`	-	Custom class for the root
`style`	`React.CSSProperties`	-	Custom inline style for the root
`classNames`	`{ item?: ClassNameValue; groupHeader?: ClassNameValue }`	-	Custom classes for each part (`groupHeader` is unused in `Order`)
`styles`	`{ item?: React.CSSProperties; groupHeader?: React.CSSProperties }`	-	Custom inline styles for each part (`groupHeader` is unused in `Order`)

List

On this page