thekits.dev
EN

v5.0.1 · Licencia MIT · TypeScript

listkit

Vistas de lista estandarizadas y responsivas para React.

Tabla / tarjetas, búsqueda, filtros avanzados, paginación, ordenamiento, SSR y theming — listo para usar.

Comenzar Playground GitHub npm

Instalación

npm install listkit

Características

Todo lo que incluye el paquete, según su propio README.

  • Configuración declarativa

    un solo defineListConfig<T>() describe toda la vista de lista (búsqueda, filtros, columnas, tarjeta, acciones, tema).

  • Responsivo por defecto

    cambia automáticamente entre tabla (escritorio) y tarjetas (tablet/móvil); sigue el viewport.

  • Adaptadores de datos

    renderiza arrays en memoria o conecta una fuente asíncrona (REST, server actions de Next.js, Dexie). Búsqueda/paginación/filtros fluyen a través del adaptador, por lo que pueden ejecutarse en el servidor.

  • Caché integrada

    las respuestas se mantienen en memoria con staleTime configurable. Volver a una página reciente muestra los datos al instante; stale-while-revalidate refresca silenciosamente en segundo plano.

  • Hook de datos remplazable

    inyecta tu propio useListData (ej. TanStack Query) para refetch en segundo plano, reintentos y caché entre componentes sin acoplar el paquete a ninguna librería.

  • Listo para SSR

    pasa la primera página obtenida en el servidor como initialData y la lista renderiza filas reales en el HTML inicial (SEO, sin flash de carga, hidrata sin volver a fetchear). buildListQuery reconstruye la query exacta en el servidor para que coincida con el cliente.

  • Filtros avanzados

    text, select, multi-select, date-range, number-range, boolean; los valores son validados con Zod y sincronizados a la URL. Los filtros pueden organizarse en 1 o 2 columnas para ahorrar espacio.

  • Ordenamiento de columnas

    marca columnas como sortable; los encabezados ciclan asc → desc → off, sincronizan la URL y fluyen al adaptador (query.sort). La siguiente página se prefetch en idle para que la paginación hacia adelante sea instantánea.

  • Adaptadores de router

    sincronizan el estado de la lista a la URL vía adaptadores remplazables: Next.js, React Router, o el adaptador de navegador sin framework.

  • Theming

    8 paletas integradas o tu propio tema personalizado; por lista o global.

  • Tarjetas personalizadas

    usa el chrome de tarjeta integrado, o bareCard para insertar un componente de tarjeta completamente personalizado.

  • Refrescar en mutación

    useListRefresh() refetchea la lista después de un delete/edit, sin recargar la página.

  • Atajos de teclado

    ⌘ K enfoca búsqueda, + abre filtros, Shift + V cambia la vista, Shift + D cambia la densidad, - quita el último filtro, ←/→ página anterior/siguiente, Shift + ←/Shift + → primera/última página.

  • Slots de encabezado

    coloca métricas/badges sobre el título con headerContent={{ left, center, right }}.

  • Gestor de columnas

    table.columnControl permite ocultar/mostrar y reordenar columnas; persiste en localStorage (o tu propio ColumnStorage).

  • Exportar a CSV

    agrega un botón de exportación en el toolbar con export: página actual por defecto; "exportar todo" se autodetecta para data en memoria, o se conecta con fetchAll para una fuente en el servidor (sin recorrer el adaptador página por página). Respeta las columnas visibles y su orden, con exportValue/exportable por columna.

  • Selección de filas y acciones masivas

    selection agrega checkboxes y una barra de selección con tus acciones masivas. La selección es por clave, sobrevive a la paginación y se limpia cuando cambia el dataset; combina con "exportar selección".

  • Imágenes optimizadas

    <ListImage> para tablas/tarjetas densas: lazy-load, decodificación asíncrona, placeholder shimmer, fallback de error y un slot para inyectar next/image.

  • Encabezado fijo, densidad, reordenar y redimensionar

    opciones opcionales de table (stickyHeader, density, reorderable, resizable); las elecciones del usuario persisten en localStorage.

  • Filtros colapsables + búsqueda rápida

    los sidebars largos tienen secciones colapsables (collapsible) y una caja de búsqueda de filtros.

  • Slider de rango

    un filtro number-range puede renderizar como slider de dos manijas (display: 'slider', min/max/step/formatValue).

  • Límites numéricos según el locale

    los inputs de number-range leen y escriben números agrupados (1,234.56 en en-US, 1.234,56 en de-DE), y el chip aplicado usa formatValue cuando el filtro declara uno. Un límite que no sea un número finito se lee como vacío, así que uno malformado nunca llega a la query.

  • Componible + type-safe

    usa <ListView>, o baja de nivel a Toolbar, Table, Cards, Pagination, FilterSidebar, …

Puntos de entrada

Importa solo lo que usas; cada subpath se optimiza de forma independiente.

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

On this page

InstalaciónCaracterísticasPuntos de entrada