AkiTable

Akitable is a feature-rich table component for displaying, editing, and interacting with tabular data.

It supports pagination, row selection, bulk actions, editable cells, and custom headers/footers.

Installation

pnpm add @akinon/akitable

Basic Usage

import { Akitable, type AkitableColumn, type AkitableData } from '@akinon/akitable';
import { useAkilocale } from '@akinon/akilocale';

interface Product {
  id: number;
  name: string;
  price: number;
  status: string;
}

export const ProductTable = () => {
  const { locale } = useAkilocale();

  const columns: AkitableColumn[] = [
    {
      title: 'Name',
      dataIndex: 'name',
      key: 'name'
    },
    {
      title: 'Price',
      dataIndex: 'price',
      key: 'price',
      render: (value: number) => 
        new Intl.NumberFormat(locale.lng, { style: 'currency', currency: 'USD' }).format(value)
    },
  {
    title: 'Status',
    dataIndex: 'status',
    key: 'status'
  }
];

  const data: Product[] = [
    { id: 1, name: 'Product A', price: 29.99, status: 'Active' },
    { id: 2, name: 'Product B', price: 49.99, status: 'Inactive' },
    { id: 3, name: 'Product C', price: 19.99, status: 'Active' }
  ];

  return (
    <Akitable
      columns={columns}
      data={data}
      rowKey="id"
    />
  );
};

Props

Prop	Type	Description
columns	AkitableColumn[]	Column definitions for the table
data	AkitableData[] | AkitablePaginatedData	Data source (array or paginated response)
rowKey	string	Unique key field for each row
actions	AkitableAction[]	Bulk actions for selected rows
header	AkitableHeaderProps	Header configuration
footer	AkitableFooterProps	Footer configuration
isLoading	boolean	Loading state
maxColumnContent	boolean	Set max-content for horizontal scroll (default: true)
pagination	AkitablePaginationProps	Pagination configuration
onPaginationChanged	(page: number, size: number) => void	Pagination change callback
onRowClick	(record, event?, rowIndex?) => void	Row click callback
onRowEdit	(modifiedRecord, payload) => void | Promise<void>	Row edit callback
onChangeSorter	(sorter) => void	Sorter change callback

Pagination

Akitable supports server-side pagination with a standardized paginated response format:

import { useState, useEffect } from 'react';
import { 
  Akitable, 
  type AkitablePaginatedData, 
  type AkitablePaginationProps 
} from '@akinon/akitable';

export const PaginatedTable = () => {
  const [data, setData] = useState<AkitablePaginatedData>({
    count: 0,
    results: []
  });
  const [pagination, setPagination] = useState<AkitablePaginationProps>({
    page: 1,
    size: 20
  });

  useEffect(() => {
    fetchData(pagination.page, pagination.size);
  }, [pagination]);

  const fetchData = async (page: number, size: number) => {
    const response = await api.getProducts({ page, size });
    setData(response); // { count: 100, results: [...] }
  };

  const handlePaginationChange = (page: number, size: number) => {
    setPagination({ page, size });
  };

  return (
    <Akitable
      columns={columns}
      data={data}
      rowKey="id"
      pagination={pagination}
      onPaginationChanged={handlePaginationChange}
    />
  );
};

Paginated Data Format

interface AkitablePaginatedData {
  count: number;           // Total number of items
  next?: string | null;    // URL for next page (optional)
  previous?: string | null;// URL for previous page (optional)
  results: AkitableData[]; // Current page items
}

Page Sizes

Available page sizes: 20, 50, 100, 250

Column Configuration

Columns extend Ant Design's TableColumnType with additional properties:

interface AkitableColumn extends TableColumnType<AkitableData> {
  copyable?: boolean;  // Enable copy to clipboard
  editable?: boolean;  // Enable inline editing
}

Basic Columns

const columns: AkitableColumn[] = [
  {
    title: 'Name',
    dataIndex: 'name',
    key: 'name',
    width: 200
  },
  {
    title: 'Email',
    dataIndex: 'email',
    key: 'email',
    copyable: true  // Show copy button
  },
  {
    title: 'Created At',
    dataIndex: 'createdAt',
    key: 'createdAt',
    render: (date: string) => new Date(date).toLocaleDateString()
  }
];

Sortable Columns

const columns: AkitableColumn[] = [
  {
    title: 'Name',
    dataIndex: 'name',
    key: 'name',
    sorter: true  // Enable sorting
  }
];

const handleSorterChange = (sorter: SorterResult | SorterResult[]) => {
  // sorter.field, sorter.order ('ascend' | 'descend' | null)
  console.log('Sort changed:', sorter);
};

<Akitable
  columns={columns}
  data={data}
  rowKey="id"
  onChangeSorter={handleSorterChange}
/>

Editable Columns

const columns: AkitableColumn[] = [
  {
    title: 'Name',
    dataIndex: 'name',
    key: 'name',
    editable: true  // Enable inline editing
  },
  {
    title: 'Price',
    dataIndex: 'price',
    key: 'price',
    editable: true
  }
];

const handleRowEdit = async (record: AkitableData, payload: AkitableData) => {
  // record: original row data
  // payload: edited field values
  await api.updateProduct(record.id, payload);
};

<Akitable
  columns={columns}
  data={data}
  rowKey="id"
  onRowEdit={handleRowEdit}
/>

Bulk Actions

Add bulk actions for selected rows:

import type { AkitableAction } from '@akinon/akitable';

const actions: AkitableAction[] = [
  {
    label: 'Delete Selected',
    onSelect: (selectedRowKeys: React.Key[]) => {
      console.log('Deleting:', selectedRowKeys);
      // Handle bulk delete
    }
  },
  {
    label: 'Export Selected',
    onSelect: (selectedRowKeys: React.Key[]) => {
      console.log('Exporting:', selectedRowKeys);
      // Handle bulk export
    }
  }
];

<Akitable
  columns={columns}
  data={data}
  rowKey="id"
  actions={actions}
/>

When actions are provided, row selection checkboxes appear automatically.

Header Configuration

Customize the table header with title, extra content, and download actions:

import { Button } from '@akinon/ui-button';

<Akitable
  columns={columns}
  data={data}
  rowKey="id"
  pagination={pagination}
  header={{
    title: 'Products',
    extra: (
      <Button type="primary" onClick={handleAddProduct}>
        Add Product
      </Button>
    ),
    downloadActions: (
      <>
        <Button onClick={handleExportCsv}>CSV</Button>
        <Button onClick={handleExportXls}>Excel</Button>
      </>
    ),
    downloadActionsSlotWidth: 120,
    reserveDownloadActionsSpace: true
  }}
/>

Header Props

Prop	Type	Description
title	string	Table title (displays with total count)
extra	ReactNode	Additional content (buttons, filters, etc.)
downloadActions	ReactNode	Download/export action buttons
downloadActionsSlotWidth	number	Reserved width for download actions slot
reserveDownloadActionsSpace	boolean	Keep slot width when empty (default: true)

Footer Configuration

Add custom content to the table footer:

import { useAkilocale } from '@akinon/akilocale';

const TableWithFooter = () => {
  const { locale } = useAkilocale();
  const totalAmount = 1234.56;

  return (
    <Akitable
      columns={columns}
      data={data}
      rowKey="id"
      footer={{
        extra: (
          <div>
            <span>
              Total: {
                new Intl.NumberFormat(locale.lng, { style: 'currency', currency: 'USD' })
                  .format(totalAmount)
                }
            </span>
          </div>
        )
      }}
    />
  );
};

Row Events

Row Click

const handleRowClick = (
  record: AkitableData,
  event?: React.MouseEvent<HTMLElement>,
  rowIndex?: number
) => {
  console.log('Row clicked:', record);
  // Navigate to detail page, open modal, etc.
};

<Akitable
  columns={columns}
  data={data}
  rowKey="id"
  onRowClick={handleRowClick}
/>

Row Status

Rows can have visual status indicators:

import { AkitableRowStatus } from '@akinon/akitable';

const data = [
  { id: 1, name: 'Processing...', rowStatus: AkitableRowStatus.PENDING },
  { id: 2, name: 'Failed item', rowStatus: AkitableRowStatus.ERROR },
  { id: 3, name: 'Normal item' }
];

Available statuses:

• AkitableRowStatus.PENDING - Shows pending/loading state

• AkitableRowStatus.ERROR - Shows error state

Loading State

const [isLoading, setIsLoading] = useState(false);

<Akitable
  columns={columns}
  data={data}
  rowKey="id"
  isLoading={isLoading}
/>

Complete Example

import { useState, useEffect } from 'react';
import { 
  Akitable, 
  type AkitableColumn, 
  type AkitablePaginatedData,
  type AkitablePaginationProps,
  type AkitableAction,
  type SorterResult
} from '@akinon/akitable';
import { Button } from '@akinon/ui-button';
import { useAkilocale } from '@akinon/akilocale';

interface Order {
  id: number;
  orderNumber: string;
  customer: string;
  total: number;
  status: string;
  createdAt: string;
}

export const OrdersTable = () => {
  const { locale } = useAkilocale();

  const columns: AkitableColumn[] = [
    {
      title: 'Order Number',
      dataIndex: 'orderNumber',
      key: 'orderNumber',
      copyable: true
    },
    {
      title: 'Customer',
      dataIndex: 'customer',
      key: 'customer',
      sorter: true
    },
    {
      title: 'Total',
      dataIndex: 'total',
      key: 'total',
      render: (value: number) => 
        new Intl.NumberFormat(locale.lng, { style: 'currency', currency: 'USD' }).format(value),
      sorter: true
    },
  {
    title: 'Status',
    dataIndex: 'status',
    key: 'status'
  },
  {
    title: 'Created At',
    dataIndex: 'createdAt',
    key: 'createdAt',
    render: (date: string) => new Date(date).toLocaleDateString(),
    sorter: true
  }
  ];

  const [data, setData] = useState<AkitablePaginatedData>({
    count: 0,
    results: []
  });
  const [pagination, setPagination] = useState<AkitablePaginationProps>({
    page: 1,
    size: 20
  });
  const [isLoading, setIsLoading] = useState(false);
  const [sorter, setSorter] = useState<SorterResult | null>(null);

  useEffect(() => {
    fetchOrders();
  }, [pagination, sorter]);

  const fetchOrders = async () => {
    setIsLoading(true);
    try {
      const response = await api.getOrders({
        page: pagination.page,
        size: pagination.size,
        sortField: sorter?.field,
        sortOrder: sorter?.order
      });
      setData(response);
    } finally {
      setIsLoading(false);
    }
  };

  const handlePaginationChange = (page: number, size: number) => {
    setPagination({ page, size });
  };

  const handleSorterChange = (newSorter: SorterResult | SorterResult[]) => {
    const result = Array.isArray(newSorter) ? newSorter[0] : newSorter;
    setSorter(result);
  };

  const handleRowClick = (record: Order) => {
    // Navigate to order detail
    router.push(`/orders/${record.id}`);
  };

  const actions: AkitableAction[] = [
    {
      label: 'Mark as Shipped',
      onSelect: async (selectedKeys) => {
        await api.bulkUpdateStatus(selectedKeys, 'shipped');
        fetchOrders();
      }
    },
    {
      label: 'Delete',
      onSelect: async (selectedKeys) => {
        await api.bulkDelete(selectedKeys);
        fetchOrders();
      }
    }
  ];

  return (
    <Akitable
      columns={columns}
      data={data}
      rowKey="id"
      isLoading={isLoading}
      pagination={pagination}
      onPaginationChanged={handlePaginationChange}
      onChangeSorter={handleSorterChange}
      onRowClick={handleRowClick}
      actions={actions}
      header={{
        title: 'Orders',
        extra: (
          <Button type="primary" onClick={() => router.push('/orders/new')}>
            Create Order
          </Button>
        ),
        downloadActions: (
          <Button onClick={handleExportOrders}>Export</Button>
        )
      }}
    />
  );
};

Internationalization

Akitable uses @akinon/akilocale for built-in translations. Default labels (pagination, actions, etc.) are provided in English and Turkish.

Best Practices

1. Always provide rowKey - Use a unique identifier field for proper row tracking

2. Use server-side pagination - For large datasets, implement pagination with AkitablePaginatedData

3. Handle loading states - Show loading indicator during data fetches

4. Define column widths - Prevent layout shifts with fixed column widths

5. Use bulk actions wisely - Provide clear, actionable labels for bulk operations