Quick start

Installation

npm install --save @21jumpclick/data-table

Peer dependencies

react, react-dom and Mui v6 are peer dependencies, meaning you should ensure they are installed before installing DataTable. If you plan to use React query you must also install it according to peer dependencies

"peerDependencies": {
    "@mui/icons-material": "^6.0.0",
    "@mui/material": "^6.0.0",
    "@emotion/react": "^11.5.0",
    "@emotion/styled": "^11.3.0",
    "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
    "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0",
    "@tanstack/react-query": "^5.0.0"
}

Provider

We provide <DataTableProvider /> component, which can configure Datatables to the rest of your app

Usage

import React from 'react'
import { ThemeProvider } from "@mui/material";
import { DataTableProvider } from '@21jumpclick/data-table'
import options from './options'
import theme from './theme'
import App from './App'

const root = ReactDOM.createRoot(document.getElementById('root'))
root.render(
  <ThemeProvider theme={theme}>
    <DataTableProvider values={options}>
      <App/>
    </DataTableProvider>,
  </ThemeProvider>
)

Options

export interface DataTableContextProps {
  /** TranslationLocale is provided in fr and en but can be created following our files as [enLocale]{@link import('/lib/i18n/en.ts').en}, default: en.ts */
  translationLocale: TranslationLocale;
  /** You can provide your own columnTypeDefs following this file [userTypeDef]{@link import('/src/ColumnTypeDef/usersTypeDef.tsx').usersTypeDef}, default: [] */
  columnTypeDefs: ColumnTypeDef[];
  /** Simple method to prettify number, default: Intl.NumberFormat */
  // biome-ignore lint: intended any
  numberFormatter: (val: any) => string;
  /** Override [DefaultTableState]{@link import('lib/DataTable/useDataTable.ts').DefaultTableState} with you own to be applied to all subsequent DataTable */
  defaultTableState: DefaultTableState;
  /** [ISO 639-2 code](https://www.loc.gov/standards/iso639-2/php/code_list.php). Should be used if you don't want to use dateFnsLocale */
  i18nLocale: string;
  /** DateFns [Locale object](https://date-fns.org/v4.1.0/docs/I18n) imported from 'date-fns/locale' */
  dateFnsLocale: Locale;
  /** You can provide your own smartFilterItems following this [userSmartFilterItem]{@link import('/src/CustomSmartFilters/userSmartFilter.tsx').userSmartFilterItem */
  smartFilterItems: Record<string, SmartFilterItem>;
}

BasicDataTable

Usage

import { BasicDataTable } from '@21jumpclick/data-table';

<BasicDataTable
  columns={columns}
  data={data}
  isLoading={false}
/>

Options

export interface BasicDataTableProps<T extends RowData> extends DefaultDataTableProps<T> {
  /** Array of data that contains all rows */
  data: T[];
  /** Boolean to trigger datatable loading state */
  isLoading?: boolean;
}

ClientDataTable

Usage

import { ClientDataTable } from '@21jumpclick/data-table';

<ClientDataTable
  columns={columns}
  useTableQuery={useTableQuery}
/>

Options

export interface ClientDataTableProps<T extends RowData> extends DefaultDataTableProps<T> {
  /** Hook that return a react-query result returning a array of data that contains all rows */
  useTableQuery: () => UseQueryResult<T[]>;
}

ServerDataTable

Usage

import { ServerDataTable } from '@21jumpclick/data-table';

<ServerDataTable
  columns={columns}
  useTableQuery={useTableQuery}
/>

Options

interface Filter {
  /** Field take a [ColumnDef.accessorKey]{@link import('@tanstack/react-table').ColumnDef.accessorKey} or [ColumnDef.id]{@link import('@tanstack/react-table').ColumnDef.id} */
  field: string;
  /** Value to filter */
  value: string | number | boolean | null;
  /** type of filter can be any [SmartFilterOperation]{@link import('/lib/smartFilters').SmartFilterOperation} or customs one you define in DataTableProvider
   * @see [smartFilterItems]{@link import('/lib/Provider').DataTableContextProps.smartFilterItems} */
  type: string;
}

export interface TableQuery {
  /** Number of rows to skip */
  offset?: number;
  /** Number of row to display */
  limit?: number;
  /** Search string */
  search?: string | null;
  /** Order of current orderBy column */
  order?: "asc" | "desc" | null;
  /** OrderBy params take a [ColumnDef.accessorKey]{@link import('@tanstack/react-table').ColumnDef.accessorKey} or [ColumnDef.id]{@link import('@tanstack/react-table').ColumnDef.id} */
  orderBy?: string | null;
  /** Array of current filters to be applied to the datatable */
  filters?: Filter[];
}

export interface ServerDataTableProp<T extends RowData>
  extends DefaultDataTableProps<T> {
  /** A hooks that take a {@link TableQuery} as parameter and return a TanStack query with an array of data that contains partial data and a count of all rows */
  useTableQuery: (params: TableQuery) => UseQueryResult<{ data: T[]; count: number }>;
}

Shared properties

import type {
  RowSelectionState,
  ColumnDef,
  Row,
  OnChangeFn,
  GroupingState,
  PaginationState,
  SortingState,
  VisibilityState
} from "@tanstack/react-table"
import type { SmartFilter } from "@21jumpclick/data-table"

export interface DataTableState {
  /** Set to true to enableQueryParams, default: false */
  enableQueryParams: boolean;
  /** Array of [ColumnDef.accessorKey]{@link import('@tanstack/react-table').ColumnDef.accessorKey} or [ColumnDef.id]{@link import('@tanstack/react-table').ColumnDef.id}
   * @see [GroupingState]{@link import('@tanstack/react-table').GroupingState}
   */
  groupBy: GroupingState;
  /** Current page size and page index
   * @see [PaginationState]{@link import('@tanstack/react-table').PaginationState}
   */
  pagination: PaginationState;
  /** Search string */
  search?: string;
  /** Size of the rows */
  size: "small" | "medium";
  /** Array of [SmartFilter]{@link import('/lib/DataTable/features').SmartFilter} */
  smartFilters: SmartFilter[];
  /** Array of columns to sort
   * @see [SortingState]{@link import('@tanstack/react-table').SortingState}
   * */
  sortBy: SortingState;
  /** Columns to be hidden */
  visibility?: Partial<VisibilityState>;
}

export interface DefaultDataTableProps<T extends RowData>
  extends DataTableState {
  /** Columns is a standard ColumnDef from [TanStack Table](https://tanstack.com/table/latest) extended with our own features:
   - `columnType?: ColumnType` base ColumnType or your own custom, default: 'string'
   - `enableAggregation?: boolean` set to false to disable aggregation on current column, default: true
   - `enableSmartFilter?: boolean` set to false to disable smart filter on current column, default: true
   */
  columns: ColumnDef<T>[];
  /** If set to true display a checkbox for first column and emit on onRowSelectionChange whenever a checkbox state change */
  enableRowSelection?: boolean;
  /** If set to any fn add mui hover class name for theming and emit row data on row click  */
  onRowClick?: (row: Row<T>) => void;
  /** When a riw checkbox state change emit current rows selected */
  onRowSelectionChange?: OnChangeFn<RowSelectionState>;
  /** Add Components to start or end of DataTable toolbar such as button for custom actions */
  additionalTools?: {
    start?: Array<() => JSX.Element>;
    end?: Array<() => JSX.Element>;
  };
}

DataTableRef

Usage

import { ClientDataTable } from '@21jumpclick/data-table';
import { useRef } from 'react';

const ref = useRef<DefaultDataTableRef<T> | null>(null);

ref?.table.setLoading(true)

< ClientDataTable
ref = {ref}
columns = {columns}
useTableQuery = {useTableQuery}
/>

Options

import type { LegacyRef } from 'react'
import type { Table, RowData } from '@tanstack/react-table'

export interface DefaultDataTableRef<T extends RowData> {
  /** current table instance from tanstack/react-table */
  table: Table<T>;
  /** current table element ref */
  tableRef: LegacyRef<HTMLTableElement>;
  /** current toolbar element ref */
  toolbarRef: LegacyRef<HTMLDivElement>;
  /** current table container element ref */
  containerRef: LegacyRef<HTMLDivElement>;
  /** current pagination element ref */
  paginationRef: LegacyRef<HTMLDivElement>;
}

export interface ClientDataTableRef<T extends RowData>
  extends DefaultDataTableRef<T> {
  query: UseQueryResult<T[]>;
}

export interface ServerDataTableRef<T extends RowData>
  extends DefaultDataTableRef<T> {
  query: UseQueryResult<{ data: T[]; count: number }>;
}

Theming

DataTable css is built with MUI and a theme with cssVariables: true must be provided for optimal rendering

example

Create custom column type

example 1

example 2

Create custom smart filter

example