K-Grid

A lightweight, customizable React data grid component built on top of TanStack Table and MUI Joy UI.

Features

• 🔍 Built-in search and filtering capabilities
• 🔄 Column sorting with visual indicators
• 📏 Customizable column widths
• 🎨 Clean, modern UI based on Joy UI
• 🧩 Fully typed with TypeScript
• 🔌 Extensible API for custom functionality
• 🕶️ Column visibility control with hide property
• 🆔 Automatic column ID resolution from accessorKey or header
• 📄 Pagination with customizable page sizes

Installation

# npm
npm install kimia-grid

# yarn
yarn add kimia-grid

# pnpm
pnpm add kimia-grid

Basic Usage

import { useRef } from 'react';
import { KGrid, KColumnDef, GridApi } from 'k-grid';

// Define your data type
type User = {
  id: string;
  name: string;
  email: string;
};

// Sample data
const users: User[] = [
  { id: '1', name: 'John Doe', email: '[email protected]' },
  { id: '2', name: 'Jane Smith', email: '[email protected]' },
  { id: '3', name: 'Bob Johnson', email: '[email protected]' },
];

// Define columns
const columns: KColumnDef<User>[] = [
  {
    header: 'ID',
    accessorKey: 'id',
    width: 70, // Fixed width in pixels
  },
  {
    header: 'Name',
    accessorKey: 'name',
    minWidth: 200, // Minimum width
  },
  {
    header: 'Email',
    accessorKey: 'email',
    maxWidth: 300, // Maximum width
    hide: true, // This column will be hidden by default
  },
];

function App() {
  const gridApi = useRef<GridApi>(null);

  return (
    <div style={{ height: '400px', width: '100%' }}>
      <KGrid 
        ref={gridApi}
        rowData={users} 
        columns={columns} 
        pagination={true}
        paginationOptions={[10, 20, 50]}
      />
    </div>
  );
}

Advanced Features

Pagination

K-Grid supports client-side pagination with customizable page sizes:

<KGrid
  rowData={data}
  columns={columns}
  pagination={true}
  paginationSize={20} // Default page size
  paginationOptions={[10, 20, 50, 100]} // Available page size options
/>

The pagination controls include:

• Page size selector
• Previous/next page buttons
• Automatic row count calculation

Column Visibility Control

You can control column visibility using the hide property in column definitions:

const columns: KColumnDef<User>[] = [
  {
    header: 'ID',
    accessorKey: 'id',
    hide: true, // This column will be hidden by default
  },
  {
    header: 'Name',
    accessorKey: 'name',
  },
  // ...other columns
];

The column ID is automatically resolved in this order:

1. Explicit id property
2. accessorKey (if provided)
3. header string (if provided)

Global Search

import { useRef } from 'react';
import { Input } from '@mui/joy';
import { KGrid, GridApi } from 'k-grid';

function App() {
  const gridApi = useRef<GridApi>(null);

  const handleSearch = (searchText: string) => {
    if (gridApi.current) {
      gridApi.current.setGlobalFilter(searchText);
    }
  };

  return (
    <div>
      <Input
        placeholder="Search..."
        onChange={(e) => handleSearch(e.target.value)}
      />
      <KGrid 
        ref={gridApi}
        rowData={data} 
        columns={columns} 
      />
    </div>
  );
}

Column Filtering

Column filtering is enabled by default. To enable filtering for specific columns:

const columns: KColumnDef<User>[] = [
  {
    header: 'Name',
    accessorKey: 'name',
    enableColumnFilter: true, // Enable filtering for this column
  },
  // ...other columns
];

Custom Sorting

const columns: KColumnDef<User>[] = [
  {
    header: 'Created Date',
    accessorKey: 'createdAt',
    sortingFn: 'datetime', // Use built-in datetime sorting
  },
  // ...other columns
];

// Set default sorting
<KGrid 
  rowData={data} 
  columns={columns} 
  defaultSorting={[{ id: 'createdAt', desc: true }]}
/>

Column Width Configuration

const columns: KColumnDef<User>[] = [
  {
    header: 'ID',
    accessorKey: 'id',
    width: 70, // Fixed width in pixels
  },
  {
    header: 'Actions',
    cell: () => <EditIcon size={14} />,
    width: 50, // Narrow column for icons
    enableSorting: false,
  },
  {
    header: 'Name',
    accessorKey: 'name',
    minWidth: 200, // Minimum width
  },
  {
    header: 'Description',
    accessorKey: 'description',
    maxWidth: 400, // Maximum width
  },
];

Striped Rows

<KGrid 
  rowData={data} 
  columns={columns} 
  stripe="odd" // or "even"
/>

Empty State Handling

K-Grid provides a customizable empty state when no data is available:

<KGrid
  rowData={[]}
  columns={columns}
  noDataComponent={
    <Box sx={{ textAlign: 'center' }}>
      <Typography level="h4" sx={{ mb: 1 }}>
        No se encontraron resultados
      </Typography>
      <Typography level="body-md">
        Intenta ajustar tus filtros de búsqueda
      </Typography>
    </Box>
  }
/>

You can also use a simple string:

<KGrid
  rowData={[]}
  columns={columns}
  noDataComponent="No data available"
/>

If no noDataComponent is provided, a default message will be shown.

Expandable Rows

K-Grid supports expandable rows with custom sub-components:

// Define a column with an expander button
const columns: KColumnDef<User>[] = [
  {
    id: 'expander',
    header: '',
    width: 40,
    cell: ({ row }) => (
      <IconButton
        size="sm"
        variant="plain"
        onClick={() => row.toggleExpanded()}
      >
        {row.getIsExpanded() ? <ChevronDown /> : <ChevronRight />}
      </IconButton>
    ),
  },
  // ... other columns
];

// Define a sub-component to render when a row is expanded
const SubComponent = ({ row }: { row: Row<User> }) => {
  const data = row.original;
  
  return (
    <Card variant="outlined" sx={{ m: 1 }}>
      <Typography>Additional details for {data.name}</Typography>
      {/* More content here */}
    </Card>
  );
};

// Use the renderSubComponent prop
<KGrid 
  rowData={data} 
  columns={columns} 
  renderSubComponent={SubComponent}
  defaultExpanded={false} // Optional: set to true to expand all rows by default
/>

This implementation gives you complete control over how rows are expanded. You can:

1. Add an expander column with custom styling and behavior
2. Define what content appears when a row is expanded
3. Control the initial expansion state
4. Access all row data and methods in both the cell renderer and sub-component

API Reference

KGrid Props

| Prop | Type | Description | |------|------|-------------| | rowData | T[] | Array of data objects to display in the grid | | columns | KColumnDef<T>[] | Column definitions | | defaultSorting | SortingState | Initial sorting state | | globalFilter | string | Initial global filter value | | stripe | "odd" \| "even" | Row striping pattern | | renderSubComponent | (props: { row: Row<T> }) => ReactNode | Function to render content when a row is expanded | | defaultExpanded | boolean | Whether all rows should be expanded by default | | pagination | boolean | Enable pagination | | paginationSize | number | Default page size | | paginationIndex | number | Initial page index | | paginationOptions | number[] | Available page size options | | noDataComponent | ReactNode | Component or message to display when no data is available |

KColumnDef

Extends all properties from TanStack Table's ColumnDef with additional properties:

| Property | Type | Description | |----------|------|-------------| | width | number \| string | Fixed width for the column | | minWidth | number \| string | Minimum width for the column | | maxWidth | number \| string | Maximum width for the column | | hide | boolean | Whether the column should be hidden by default | | accessorKey | string | Key to access data in the row object |

GridApi

| Method | Description | |--------|-------------| | setGlobalFilter(filter: string) | Set the global filter value | | getGlobalFilter() | Get the current global filter value |

License

KSL