thekits.dev
ES

v5.0.1 · MIT license · TypeScript

listkit

Standardized, responsive list views for React.

Table / cards, search, advanced filters, pagination, sorting, SSR, and theming — out of the box.

Get started Playground GitHub npm

Installation

npm install listkit

Features

Everything the package ships, from its own README.

  • Declarative config

    one defineListConfig<T>() describes the whole list view (search, filters, table columns, card, actions, theme).

  • Responsive by default

    auto-switches between table (desktop) and cards (tablet/phone); follows the viewport.

  • Data adapters

    render in-memory arrays or plug an async source (REST, Next.js server actions, Dexie). Search/pagination/filters flow through the adapter, so they can run server-side.

  • Built-in cache

    responses are kept in memory with configurable staleTime. Returning to a recent page/filter serves data instantly; stale-while-revalidate refreshes silently in the background.

  • Pluggable data hook

    inject your own useListData (e.g. TanStack Query) for background refetch, retries, and cross-component cache without coupling the package to any library.

  • SSR-ready

    pass a server-fetched first page as initialData and the list renders real rows in the initial HTML (SEO, no loading flash, hydrates without a refetch). buildListQuery rebuilds the exact query on the server so it matches the client.

  • Advanced filters

    text, select, multi-select, date-range, number-range, boolean; values are Zod-validated and synced to the URL. Filters can be arranged in 1 or 2 columns to save space.

  • Column sorting

    mark columns sortable; headers cycle asc → desc → off, sync to the URL, and flow into the adapter (query.sort). The next page is prefetched on idle so forward pagination is instant.

  • Router adapters

    sync list state to the URL via pluggable adapters: Next.js, React Router, or the framework-free browser adapter.

  • Theming

    8 built-in palettes or your own custom theme; set per-list or globally.

  • Custom cards

    use the built-in card chrome, or bareCard to drop in a fully custom card component.

  • Refresh on mutation

    useListRefresh() refetches the list after a delete/edit, no full page reload.

  • Keyboard shortcuts

    ⌘ K focus search, + open filters, Shift + V toggle view, Shift + D toggle row density, - remove the last filter, ←/→ previous/next page, Shift + ←/Shift + → first/last page.

  • Header slots

    drop quick metrics/badges above the title with headerContent={{ left, center, right }}.

  • Column manager

    table.columnControl lets users hide/show and reorder columns; persisted to localStorage (or your own ColumnStorage).

  • CSV export

    add a toolbar export button with export: current page by default; "export all" is auto-detected for in-memory data, or wired via fetchAll for a server source (no browser page-loop). Respects the visible columns and their order, with per-column exportValue/exportable.

  • Row selection & bulk actions

    selection adds checkboxes and a selection bar with your bulk actions. Selection is key-based, survives pagination, and clears when the dataset changes; pairs with "export selected".

  • Optimized images

    <ListImage> for dense tables/cards: lazy-load, async decode, a shimmer placeholder, an error fallback, and a next/image injection slot.

  • Sticky header, density, reorder & resize

    opt-in table options (stickyHeader, density, reorderable, resizable); the user's choices persist to localStorage.

  • Collapsible filters + quick-search

    long sidebars get collapsible sections (collapsible) and a filter search box.

  • Range slider

    a number-range filter can render as a dual-thumb slider (display: 'slider', min/max/step/formatValue).

  • Locale-aware number bounds

    number-range inputs read and write grouped numbers (1,234.56 in en-US, 1.234,56 in de-DE), and the applied chip uses formatValue when the filter declares one. A bound that isn't a finite number reads as unset, so a malformed one never reaches the query.

  • Composable + type-safe

    use <ListView>, or drop down to Toolbar, Table, Cards, Pagination, FilterSidebar, …

Entry points

Import only what you use; each subpath is tree-shaken independently.

  • listkit
  • listkit/next
  • listkit/react-query
  • listkit/react-router
  • listkit/adapters
  • listkit/server
  • listkit/query
  • listkit/sql
  • listkit/mongo
  • listkit/mongoose

On this page

InstallationFeaturesEntry points