Column Configuration

Define and configure table columns with type safety

Overview

Columns in Seizen Table are defined using TanStack Table’s ColumnDef type with full TypeScript support. The library re-exports this type as SeizenTableColumn<TData> for convenience.

Basic Column Definition

The simplest way to define columns is using accessorKey:

import { type ColumnDef } from '@izumisy/seizen-table';

type Person = {
  name: string;
  age: number;
  email: string;
};

const columns: ColumnDef<Person>[] = [
  { accessorKey: 'name', header: 'Name' },
  { accessorKey: 'age', header: 'Age' },
  { accessorKey: 'email', header: 'Email' },
];

Column Types

Accessor Columns

Use accessorKey for simple property access:

const columns: ColumnDef<Person>[] = [
  {
    accessorKey: 'name',
    header: 'Full Name',
  },
];

Accessor Function Columns

Use accessorFn for computed values:

const columns: ColumnDef<Person>[] = [
  {
    id: 'fullName',
    accessorFn: (row) => `${row.firstName} ${row.lastName}`,
    header: 'Full Name',
  },
];

Display Columns

Display columns don’t access data directly:

const columns: ColumnDef<Person>[] = [
  {
    id: 'actions',
    header: 'Actions',
    cell: ({ row }) => (
      <button onClick={() => handleEdit(row.original)}>
        Edit
      </button>
    ),
  },
];

Column Properties

accessorKey · keyof TData

Property name to access data from each row

accessorFn · (row: TData) => any

Function to compute cell value from row data

id · string

Unique column identifier. Required when using accessorFn or display columns.

header · string | ((props) => ReactNode)

Column header content. Can be a string or render function.

cell · (props) => ReactNode

Custom cell renderer. Receives cell context with row, getValue(), etc.

meta · ColumnMeta

Custom metadata for plugins. Used by FilterPlugin, ColumnControl, etc.

enableSorting · boolean · default: "true"

Enable sorting for this column

enableColumnFilter · boolean · default: "true"

Enable filtering for this column

sortingFn · SortingFn

Custom sorting function

filterFn · FilterFn

Custom filter function

Custom Cell Rendering

Render custom cell content:

const columns: ColumnDef<Person>[] = [
  {
    accessorKey: 'status',
    header: 'Status',
    cell: ({ getValue }) => {
      const status = getValue() as string;
      return (
        <span className={`badge badge-${status}`}>
          {status}
        </span>
      );
    },
  },
];

Access the full row:

const columns: ColumnDef<Person>[] = [
  {
    id: 'actions',
    header: 'Actions',
    cell: ({ row }) => (
      <div>
        <button onClick={() => handleEdit(row.original)}>Edit</button>
        <button onClick={() => handleDelete(row.original)}>Delete</button>
      </div>
    ),
  },
];

Custom Header Rendering

Render custom header content:

const columns: ColumnDef<Person>[] = [
  {
    accessorKey: 'name',
    header: ({ column }) => (
      <div className="flex items-center gap-2">
        <span>Name</span>
        {column.getIsSorted() && (
          <span>{column.getIsSorted() === 'asc' ? '↑' : '↓'}</span>
        )}
      </div>
    ),
  },
];

Column Metadata

The meta property is used by plugins to add functionality:

Filter Plugin

const columns: ColumnDef<Person>[] = [
  {
    accessorKey: 'name',
    header: 'Name',
    meta: { filterType: 'string' as const },
  },
  {
    accessorKey: 'age',
    header: 'Age',
    meta: { filterType: 'number' as const },
  },
  {
    accessorKey: 'status',
    header: 'Status',
    meta: {
      filterType: 'enum' as const,
      filterEnumValues: ['active', 'inactive'],
    },
  },
];

Column Control Plugin

const columns: ColumnDef<Person>[] = [
  {
    accessorKey: 'id',
    header: 'ID',
    meta: { columnControl: { hidden: true } },
  },
];

Sorting

Enable or disable sorting per column:

const columns: ColumnDef<Person>[] = [
  {
    accessorKey: 'name',
    header: 'Name',
    enableSorting: true, // Default
  },
  {
    accessorKey: 'actions',
    header: 'Actions',
    enableSorting: false,
  },
];

Custom sorting function:

import { sortingFns } from '@tanstack/react-table';

const columns: ColumnDef<Person>[] = [
  {
    accessorKey: 'date',
    header: 'Date',
    sortingFn: sortingFns.datetime,
  },
];

Filtering

Disable filtering per column:

const columns: ColumnDef<Person>[] = [
  {
    accessorKey: 'name',
    header: 'Name',
    enableColumnFilter: true, // Default
  },
  {
    accessorKey: 'actions',
    header: 'Actions',
    enableColumnFilter: false,
  },
];

Type Safety

Columns are fully type-safe when using TypeScript:

type User = {
  id: number;
  name: string;
  email: string;
  role: 'admin' | 'user';
};

const columns: ColumnDef<User>[] = [
  {
    accessorKey: 'name', // ✅ Type-safe: 'name' exists on User
    header: 'Name',
  },
  {
    accessorKey: 'invalid', // ❌ Type error: 'invalid' doesn't exist
    header: 'Invalid',
  },
  {
    accessorKey: 'role',
    header: 'Role',
    cell: ({ getValue }) => {
      const role = getValue() as 'admin' | 'user'; // Type-safe
      return role === 'admin' ? 'Administrator' : 'User';
    },
  },
];

Advanced: flexRender

For custom table rendering, use flexRender to render column content:

import { flexRender } from '@izumisy/seizen-table';

function CustomTable<TData>({ table }) {
  const tanstack = table._tanstackTable;

  return (
    <table>
      <thead>
        {tanstack.getHeaderGroups().map((headerGroup) => (
          <tr key={headerGroup.id}>
            {headerGroup.headers.map((header) => (
              <th key={header.id}>
                {header.isPlaceholder
                  ? null
                  : flexRender(
                      header.column.columnDef.header,
                      header.getContext()
                    )}
              </th>
            ))}
          </tr>
        ))}
      </thead>
      <tbody>
        {tanstack.getRowModel().rows.map((row) => (
          <tr key={row.id}>
            {row.getVisibleCells().map((cell) => (
              <td key={cell.id}>
                {flexRender(cell.column.columnDef.cell, cell.getContext())}
              </td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  );
}

Seizen Table re-exports commonly used TanStack Table types like ColumnDef, Row, Cell, and flexRender for your convenience.