API Reference

type DataTableExtendedColumnProps<T = Record<string, unknown>> = 
  Omit<
    DataTableColumn<T>,
    | "sortable"
    | "sortKey"
    | "filter"
    | "filterPopoverProps"
    | "filterPopoverDisableClickOutside"
    | "filtering"
    | "ellipsis"
    | "noWrap"
  > & {
    extend?: FilterableExtend;
  } & (
    | { ellipsis?: boolean; noWrap?: never }
    | { ellipsis?: never; noWrap?: boolean }
  );

type FilterableExtend = {
  searchable?: boolean;
  sortable?: boolean;
  filterable?: boolean;
  filterVariant?: 
    | "text"
    | "number"
    | "date"
    | "date_range"
    | "number_range"
    | "single_select"
    | "multi_select";
  filterOptions?: 
    | FilterNumberRangeOptions
    | FilterSingleSelectOptions
    | FilterMultiSelectOptions;
};

type FilterNumberRangeOptions = {
  min: number;
  max: number;
  step?: number;
  minRange?: number;
};

type FilterSingleSelectOptions = {
  data: {
    value: string;
    label: string;
    count?: number;
    icon?: React.ReactNode;
  }[];
};
 
type FilterMultiSelectOptions = FilterSingleSelectOptions; // Same type

type UrlKeysType = {
  page: string;
  pageSize: string;
  sorts: string;
  search: string;
  filters: string;
};

type DefaultParamsType = {
  page?: number;
  pageSize?: number;
  sorts?: TSortCondition[];
  search?: TSearchCondition;
  filters?: TFilterCondition[];
};

type TSortCondition = {
  accessor: string;
  direction: "asc" | "desc";
};

type TSearchCondition = {
  accessors: string[];
  value: string;
};

type TFilterCondition = {
  variant: 
    | "text"
    | "number"
    | "date"
    | "date_range"
    | "number_range"
    | "single_select"
    | "multi_select";
  accessor: string;
  value: string | string[];
};

type DataTableProviderProps<T = Record<string, unknown>> = {
  children: React.ReactNode;
  urlKeys?: UrlKeysType;
  defaultParams?: DefaultParamsType;
  storeColumnsKey: string; // Required
  columns: DataTableExtendedColumnProps<T>[]; // Required
  originalUseDataTableColumnsResult: ReturnType<
    typeof useDataTableColumns<T>
  >; // Required
};

type DataTableSearchProps = {
  i18n?: {
    search?: string; // Default: "Search"
  };
};

type DataTableFilterProps = {
  i18n?: {
    resetFilter?: string; // Default: "Reset Filter"
  };
};

type DataTableSortListProps = {
  i18n?: {
    sort?: string; // Default: "Sort"
    addSort?: string; // Default: "Add Sort"
    resetSort?: string; // Default: "Reset Sort"
    asc?: string; // Default: "Asc"
    desc?: string; // Default: "Desc"
  };
};

type DataTableColumnsToggleProps = {
  i18n?: {
    columnsToggle?: string; // Default: "Columns Toggle"
  };
};

type DataTablePaginationProps = {
  recordsPerPageOptions?: number[]; // Default: [10, 20, 30, 40, 50]
  i18n?: {
    rowsPerPage?: string; // Default: "Rows per page"
    pageOfTotalPages?: [string, string]; // Default: ["Page", "of"]
    startEndRecordOfTotalRecords?: [string, string, string]; 
    // Default: ["", "-", "/"]
  };
};

function useDataTableContext<T = Record<string, unknown>>(): 
  DataTableContextProps<T>;

type DataTableContextProps<T> = {
  urlKeys?: UrlKeysType;
  defaultParams?: DefaultParamsType;
  storeColumnsKey: string;
  columns: DataTableExtendedColumnProps<T>[];
  originalUseDataTableColumnsResult: ReturnType<
    typeof useDataTableColumns<T>
  >;
  paginationProps?: PaginationPropsType;
  setTotalRecords?: (totalRecords: number) => void;
  setRecordsPerPageOptions?: (recordsPerPageOptions: number[]) => void;
};

function useDataTableQueryParams(): {
  page: number;
  setPage: (page: number) => void;
  pageSize: number;
  setPageSize: (pageSize: number) => void;
  sorts: TSortCondition[];
  setSorts: (sorts: TSortCondition[]) => void;
  search: TSearchCondition;
  setSearch: (search: TSearchCondition) => void;
  filters: TFilterCondition[];
  setFilters: (filters: TFilterCondition[]) => void;
  resetPage: () => void;
  resetPageSize: () => void;
  resetSorts: () => void;
  resetSearch: () => void;
  resetFilters: () => void;
  resetAll: () => void;
};

function createDataTableLoader(
  props?: Pick<DataTableContextProps, "urlKeys" | "defaultParams">
): (searchParams: Promise<SearchParams>) => Promise<{
  page: number;
  pageSize: number;
  sorts: TSortCondition[];
  search: TSearchCondition;
  filters: TFilterCondition[];
}>;

import { createDataTableLoader } from "mantine-datatable-extended/server";
 
const loader = createDataTableLoader({
  defaultParams: {
    page: 1,
    pageSize: 10,
  },
  urlKeys: {
    page: "p",
    pageSize: "ps",
    sorts: "s",
    search: "q",
    filters: "f",
  },
});
 
// In server component
const params = await loader(searchParams);

enum ESortDirection {
  ASC = "asc",
  DESC = "desc",
}

enum EFilterVariant {
  TEXT = "text",
  NUMBER = "number",
  NUMBER_RANGE = "number_range",
  DATE = "date",
  DATE_RANGE = "date_range",
  SINGLE_SELECT = "single_select",
  MULTI_SELECT = "multi_select",
}

// ❌ Error: storeColumnsKey property is required
<DataTableProvider columns={columns} {...otherProps}>
  {/* Missing storeColumnsKey */}
</DataTableProvider>

// ❌ Error: columns property is required
<DataTableProvider storeColumnsKey="table" {...otherProps}>
  {/* Missing columns */}
</DataTableProvider>

// ❌ Error: useDataTableContext must be used within a DataTableProvider
function Component() {
  const context = useDataTableContext(); // Will throw
  return null;
}

import type {
  DataTableExtendedColumnProps,
  DataTableContextProps,
  UrlKeysType,
  DefaultParamsType,
  TSortCondition,
  TSearchCondition,
  TFilterCondition,
  FilterNumberRangeOptions,
  FilterSingleSelectOptions,
  FilterMultiSelectOptions,
} from "mantine-datatable-extended";