Table Props Guide 📚

This guide explains all the props you can use with the TableGrid component. We'll start with the basic props and move on to more advanced ones.

Essential Props

These are the props you'll use most often:

`columns`

The list of columns to show in your table.

Type: Column<T>[]
Required: ✅

const columns = [
  columnHelper.accessor('name', {
    header: 'Name',
    sortable: true,
  }),
  // Add more columns...
];

`data`

The data to display in your table.

Type: T[]
Required: ✅

const data = [
  { id: 1, name: 'John' },
  { id: 2, name: 'Jane' },
];

`variant`

Choose how your table looks.

Type: "modern" | "minimal" | "classic"
Default: "modern"
Required: ❌

// Three style options:
<TableGrid variant="modern" />  // Modern look (default)
<TableGrid variant="minimal" /> // Simple look
<TableGrid variant="classic" /> // Traditional look

`maxHeight`

Set how tall your table can be.

Type: string
Required: ❌

<TableGrid maxHeight="500px" /> // Table will scroll after 500px

Search and Filter Props

`enableFiltering`

Turn on search functionality.

Type: boolean
Default: false

<TableGrid
  enableFiltering={true}
  fuzzySearchKeys={['name', 'email']}
/>

`fuzzySearchKeys`

Which fields to search in.

Type: Array<keyof T | string>
Required: Only if enableFiltering is true

// Search in name and email fields
fuzzySearchKeys={['name', 'email']}

`fuzzySearchThreshold`

How strict the search should be (0 to 1).

Type: number
Default: 0.3

fuzzySearchThreshold={0.3} // 0 = exact match, 1 = loose match

Column Management Props

`enableColumnResize`

Let users resize columns.

Type: boolean
Default: false

<TableGrid
  enableColumnResize={true}
  columnResizeMode="onChange"
/>

`columnResizeMode`

When to update column sizes.

Type: "onChange" | "onResize"
Default: "onChange"

columnResizeMode="onChange" // Update while dragging
columnResizeMode="onResize" // Update after drag ends

`columnResizeDirection`

Which way columns resize.

Type: "ltr" | "rtl"
Default: "ltr"

columnResizeDirection="ltr" // Left-to-right

Virtual Scrolling Props

`virtualization`

Settings for handling large data efficiently.

<TableGrid
  virtualization={{
    enabled: true,          // Turn on virtual scrolling
    rowHeight: 48,         // Height of each row
    overscan: 5,           // Extra rows to render
    scrollingDelay: 150,   // Delay before updating
    onEndReached: () => {  // Called at bottom of table
      loadMoreData();
    },
  }}
/>

Server-Side Props

`serverSide`

Settings for loading data from a server.

<TableGrid
  serverSide={{
    enabled: true,
    totalRows: 1000,    // Total rows in database
    pageSize: 20,       // Rows per page
    currentPage: 1,     // Current page number
    loading: false,     // Show loading state
    onFetch: async (options) => {
      // Get data from your server
      const data = await fetchFromServer(options);
      return data;
    },
  }}
/>

Styling Props

`styleConfig`

Customize how your table looks.

<TableGrid
  styleConfig={{
    // Main table styles
    container: {
      className: 'my-table',
      style: { margin: '1rem' },
    },
    
    // Header styles
    header: {
      className: 'my-header',
      style: { fontWeight: 'bold' },
      headerRowClassName: 'header-row',
    },
    
    // Body styles
    body: {
      className: 'my-body',
      style: { fontSize: '14px' },
      rowClassName: 'table-row',
      cellClassName: 'table-cell',
    },
    
    // Search box styles
    utilityStyles: {
      searchContainerClassName: 'search-box',
      searchInputClassName: 'search-input',
    },
  }}
/>

Custom Component Props

`components`

Replace default parts with your own components.

<TableGrid
  components={{
    // Custom header
    Header: ({ column, sortIcon }) => (
      <div className="my-header">
        {column.header} {sortIcon}
      </div>
    ),
    
    // Custom cell
    Cell: ({ value }) => (
      <div className="my-cell">{value}</div>
    ),
    
    // Custom empty message
    EmptyState: () => (
      <div>No data found 😢</div>
    ),
    
    // Custom loading message
    LoadingState: () => (
      <div>Loading... ⌛</div>
    ),
    
    // Custom search box
    SearchInput: ({ value, onChange }) => (
      <input
        value={value}
        onChange={(e) => onChange(e.target.value)}
        placeholder="Search..."
      />
    ),
  }}
/>

Event Props

`events`

Handle table events like sorting and filtering.

<TableGrid
  events={{
    // Called when sorting changes
    onSort: (column, direction) => {
      console.log(`Sorting by ${column} ${direction}`);
    },
    
    // Called when filter changes
    onFilter: (value) => {
      console.log(`Filtering with: ${value}`);
    },
    
    // Called when a column is resized
    onColumnResize: (columnId, width) => {
      console.log(`Column ${columnId} is now ${width}px`);
    },
    
    // Called when a row is selected
    onRowSelect: (row) => {
      console.log('Selected row:', row);
    },
  }}
/>

State Props

`state`

Control the table's state from outside.

<TableGrid
  state={{
    sortColumn: 'name',
    sortDirection: 'asc',
    filterValue: 'john',
    columnSizing: {
      columnSizes: {
        name: 200,
        email: 300,
      }
    },
  }}
/>

Ref Props

`ref`

Access table methods like scrolling.

function MyTable() {
  const tableRef = useRef<TableGridHandle>(null);
 
  const scrollToRow = () => {
    // Scroll to row number 10
    tableRef.current?.scrollTo(10);
  };
 
  return (
    <TableGrid
      ref={tableRef}
      columns={columns}
      data={data}
    />
  );
}

Best Practices 💡

Start Simple: Begin with just columns and data
Add Features Gradually: Add more props as you need them
Use TypeScript: Get better autocomplete and catch errors early
Handle Loading: Always show loading states when fetching data
Style Consistently: Use styleConfig for consistent looks
Test Thoroughly: Test all interactive features
Consider Mobile: Make sure your table works on small screens

Table Props

On this page