🎋 ZenTable

Minimalist. Premium. High-Performance.
A stylised, headless-first React data table library built with TanStack Table, Zod, and Framer Motion.

✨ Overview

ZenTable is a premium data table suite designed for developers who need both performance and aesthetics out of the box. It provides a "Zen" developer experience by handling the complex styling and interaction logic of data grids—like pinning, selection, and shadows—while remaining 100% compatible with the TanStack Table ecosystem.

🚀 Key Features

• 📌 Native Pinning Support: Flawless column and row pinning with consistent offset calculations.
• 🌓 Rich Aesthetics: Built-in glassmorphism, sleek shadows, and smooth motion transitions.
• 📐 Declarative API: Use our ZenColumn helper to define tables like an architect.
• ✅ Selection & Summary: Built-in row selection with actionable summary callbacks.
• 🧪 Type-Safe & Validated: Deeply integrated with TypeScript and Zod for runtime data integrity.
• ⚡ Optimised Shadows: Advanced CSS gradients for clear visual separation of frozen panes.

📦 Installation

npm install zentable
# or
pnpm add zentable

Peer Dependencies: Ensure you have react, react-dom, @tanstack/react-table, zod, and framer-motion installed.

🎬 Quick Start

import { ZenTable, createTableColumns, ZenColumn } from 'zentable'
import 'zentable/style.css'

const MyTable = () => {
  const data = [
    { id: '1', name: 'Zen 1', status: 'Active' },
    { id: '2', name: 'Zen 2', status: 'Pending' },
  ]

  const columnConfigs: ZenColumn<any>[] = [
    { key: 'select', type: 'select-row', width: 60 },
    { key: 'name', dataIndex: 'name', title: 'Name', sticky: 'left', width: 200 },
    { key: 'status', dataIndex: 'status', title: 'Status', width: 140 },
  ]

  const columns = createTableColumns(columnConfigs)

  return (
    <ZenTable 
      data={data} 
      columns={columns} 
      customHeight="500px"
      onRowSelectionChange={(selected) => console.log(selected)}
    />
  )
}

🛠️ API Reference

<ZenTable />

The primary wrapper that provides the premium styling, scroll management, and layout container.

| Prop | Type | Default | Description | |---|---|---|---| | data | TData[] | Required | The array of objects to display. | | columns | ColumnDef[] | Required | TanStack column definitions. | | theme | ZenTableTheme | defaultTheme | Customise colors, radius, and effects. | | customHeight | string | '400px' | Height of the scroll container. | | scrollable | boolean | true | Enables/Disables internal scrolling mechanism. | | onRowSelectionChange | (rows: TData[]) => void | — | Callback fired whenever selection changes. | | showFooter | boolean | false | Renders a polished summary footer row. |

🎨 Theme Customisation

Customise the "Zen" vibe with the theme prop:

interface ZenTableTheme {
  primaryColor?: string;     // Base color for interactive elements
  borderRadius?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'none';
  glassmorphism?: boolean;   // Enable backdrop blur and semi-transparent panels
  rowHoverEffect?: 'highlight' | 'glow' | 'none';
}

🏗️ Technical Stack

ZenTable stands on the shoulders of:

• Engine: @tanstack/react-table
• Validation: Zod
• Animation: Framer Motion

📄 License

MIT © 2025 ZenTable (Beta v0.1.0-beta.1)