Building Production-Ready Tables

export type UsersQueryParams = {
  page: number; //1-based
  limit: number;
  search?: string;
  sortBy?: string[]; //"lastName:desc"
  filter?: string[]; //"state[$contains]=tex"
};

export type PaginatedResponse<T> = {
  data: T[];
  total: number;
  page: number;
  limit: number;
};

export async function getUsers(
  params: UsersQueryParams,
): Promise<PaginatedResponse<User>> {
  const url = new URL('/api/users', location.origin);
  for (const [key, value] of Object.entries(params)) {
    if (value === undefined) continue;
    //arrays become repeated keys: sortBy=a&sortBy=b
    for (const item of [value].flat()) {
      url.searchParams.append(key, String(item));
    }
  }
  const response = await fetch(url);
  if (!response.ok) throw new Error(`GET /api/users: ${response.status}`);
  return response.json();
}

const http = axios.create({
  paramsSerializer: (params) => qs.stringify(params, { arrayFormat: 'repeat' }),
});

const { data } = await http.get<PaginatedResponse<User>>('/users', { params });

import { keepPreviousData, useQuery } from '@tanstack/react-query';
import { getUsers, type UsersQueryParams } from '../lib/users.service';

export function useUsersQuery(params: UsersQueryParams) {
  return useQuery({
    queryKey: ['users', params], //new params, new cache entry, new request
    queryFn: () => getUsers(params),
    placeholderData: keepPreviousData, //keep the old page on screen while the next one loads
  });
}

export function useTableQueryParams({ pageSize = 10 } = {}) {
  const [pagination, setPagination] = useState<ST_PaginationState>({
    pageIndex: 0,
    pageSize,
  });
  const [search, setSearch] = useState('');

  const handlers = {
    onPaginationChange: setPagination,
    onGlobalFilterChange: (value: string | undefined) => {
      setSearch(value ?? '');
      setPagination((prev) => ({ ...prev, pageIndex: 0 }));
    },
  };

  const params = {
    page: pagination.pageIndex + 1, //table is 0-based, server is 1-based
    limit: pagination.pageSize,
    search: search || undefined,
  };

  return { params, handlers, state: { pagination, globalFilter: search } };
}

//filter values can be strings, numbers or Dates (date filters)
const toParam = (value: unknown) =>
  value instanceof Date ? value.toISOString() : String(value);

export function useTableQueryParams<TData extends ST_RowData>({
  columns,
  pageSize = 10,
}: {
  columns: ST_ColumnDef<TData>[];
  pageSize?: number;
}) {
  const [pagination, setPagination] = useState<ST_PaginationState>({
    pageIndex: 0,
    pageSize,
  });
  const [search, setSearch] = useState('');
  const [sorting, setSorting] = useState<ST_SortingState>([]);
  const [columnFilters, setColumnFilters] = useState<ST_ColumnFiltersState>(
    [],
  );
  //one filter mode per column, from the column's filterFn or 'contains'
  const [columnFilterFns, setColumnFilterFns] =
    useState<ST_ColumnFilterFnsState>(() =>
      Object.fromEntries(
        columns.map((column) => [
          column.id ?? String(column.accessorKey),
          typeof column.filterFn === 'string' ? column.filterFn : 'contains',
        ]),
      ),
    );

  //new search, sort or filter: the old page number means nothing, go back to page 1
  const resetPageIndex = () =>
    setPagination((prev) => ({ ...prev, pageIndex: 0 }));

  const handlers = {
    onPaginationChange: setPagination,
    onGlobalFilterChange: (value: string | undefined) => {
      setSearch(value ?? '');
      resetPageIndex();
    },
    onSortingChange: (updater: ST_Updater<ST_SortingState>) => {
      setSorting(updater);
      resetPageIndex();
    },
    onColumnFiltersChange: (updater: ST_Updater<ST_ColumnFiltersState>) => {
      setColumnFilters(updater);
      resetPageIndex();
    },
    onColumnFilterFnsChange: (
      updater: ST_Updater<ST_ColumnFilterFnsState>,
    ) => {
      setColumnFilterFns(updater);
      resetPageIndex();
    },
  };

  //translate table state into the params YOUR server accepts
  const params: UsersQueryParams = {
    page: pagination.pageIndex + 1, //table is 0-based, server is 1-based
    limit: pagination.pageSize,
    search: search || undefined,
    sortBy: sorting.map(({ id, desc }) => `${id}:${desc ? 'desc' : 'asc'}`),
    filter: columnFilters.map(
      ({ id, value }) =>
        `${id}[$${columnFilterFns[id] ?? 'contains'}]=${toParam(value)}`,
    ),
  };

  return {
    params,
    handlers,
    state: {
      pagination,
      globalFilter: search,
      sorting,
      columnFilters,
      columnFilterFns,
    },
  };
}

const { params, handlers, state } = useTableQueryParams({ columns });
const { data, isError, isFetching, isLoading, refetch } = useUsersQuery(params);

const table = useShadcnTable({
  columns,
  data: data?.data ?? [],
  rowCount: data?.total ?? 0, //the server knows the total, the table does not
  manualPagination: true, //turn off client-side pagination
  manualSorting: true, //turn off client-side sorting
  manualFiltering: true, //turn off client-side filtering
  enableColumnFilterModes: true,
  //only the operators the server understands
  columnFilterModeOptions: [
    'contains',
    'startsWith',
    'endsWith',
    'equals',
    'notEquals',
  ],
  ...handlers,
  stToolbarAlertBannerProps: isError
    ? {
        className: 'border-destructive text-destructive',
        children: 'Error loading data',
      }
    : undefined,
  state: {
    ...state,
    isLoading, //first load only: skeleton rows
    showProgressBars: isFetching, //every later request: thin progress bar
    showAlertBanner: isError,
  },
});