tanstack-table-search-params/dist/index-BaZex4Hb.d.mts

React Hook for syncing TanStack Table state with URL search params

import { TableState, OnChangeFn, Updater } from '@tanstack/react-table';
import { ParsedUrlQuery } from 'node:querystring';

type Query = ParsedUrlQuery;
type Router<URL extends string = string> = {
    query: Query;
    navigate(url: URL): void;
    pathname: string;
};

type State = Pick<TableState, "globalFilter" | "sorting" | "pagination" | "columnFilters" | "columnOrder" | "rowSelection" | "columnVisibility">;
declare const PARAM_NAMES: {
    readonly GLOBAL_FILTER: "globalFilter";
    readonly SORTING: "sorting";
    readonly PAGE_INDEX: "pageIndex";
    readonly PAGE_SIZE: "pageSize";
    readonly COLUMN_FILTERS: "columnFilters";
    readonly COLUMN_ORDER: "columnOrder";
    readonly ROW_SELECTION: "rowSelection";
    readonly COLUMN_VISIBILITY: "columnVisibility";
};
type Returns = {
    /**
     * Tanstack Table's state
     */
    state: Partial<State>;
    /**
     * Tanstack Table's `onChangeGlobalFilter` function
     */
    onGlobalFilterChange?: OnChangeFn<State["globalFilter"]>;
    /**
     * Tanstack Table's `onChangeSorting` function
     */
    onSortingChange?: OnChangeFn<State["sorting"]>;
    /**
     * Tanstack Table's `onChangePagination` function
     */
    onPaginationChange?: OnChangeFn<State["pagination"]>;
    /**
     * Tanstack Table's `onChangeColumnFilters` function
     */
    onColumnFiltersChange?: OnChangeFn<State["columnFilters"]>;
    /**
     * Tanstack Table's `onChangeColumnOrder` function
     */
    onColumnOrderChange?: OnChangeFn<State["columnOrder"]>;
    /**
     * Tanstack Table's `onChangeRowSelection` function
     */
    onRowSelectionChange?: OnChangeFn<State["rowSelection"]>;
    /**
     * Tanstack Table's `onChangeColumnVisibility` function
     */
    onColumnVisibilityChange?: OnChangeFn<State["columnVisibility"]>;
    onStateChange: (updater: Updater<TableState>) => void;
};
type Options = {
    /**
     * The custom names of query parameters.
     *
     * @link [README](https://github.com/taro-28/tanstack-table-search-params?tab=readme-ov-file#custom-query-param-name)
     */
    paramNames?: {
        [KEY in keyof State]?: KEY extends "pagination" ? {
            pageIndex: string;
            pageSize: string;
        } | ((defaultParamName: {
            pageIndex: string;
            pageSize: string;
        }) => {
            pageIndex: string;
            pageSize: string;
        }) : string | ((key: KEY) => string);
    };
    /**
     * The default values of a query parameter.
     *
     * The "default value" is the value that is used as the `state` when the query parameter is not present.
     *
     * @link [README](https://github.com/taro-28/tanstack-table-search-params?tab=readme-ov-file#custom-default-value)
     */
    defaultValues?: Partial<State>;
    /**
     * The custom encoders of query parameters.
     *
     * It is used with the `decoders` option.
     *
     * @link [README](https://github.com/taro-28/tanstack-table-search-params?tab=readme-ov-file#custom-encoder-decoder)
     */
    encoders?: {
        [KEY in keyof State]?: (value: State[KEY]) => Query;
    };
    /**
     * The custom decoders of query parameters.
     *
     * It is used with the `encoders` option.
     *
     * @link [README](https://github.com/taro-28/tanstack-table-search-params?tab=readme-ov-file#custom-encoder-decoder)
     */
    decoders?: {
        [KEY in keyof State]?: (query: Query) => State[KEY];
    };
    /**
     * The debounce milliseconds of a query parameter.
     *
     * @link [README](https://github.com/taro-28/tanstack-table-search-params?tab=readme-ov-file#debounce)
     */
    debounceMilliseconds?: {
        [KEY in keyof State]?: number;
    } | number;
    /**
     * The enabled states of synchronization between the state and the query parameter.
     *
     * @link [README](https://github.com/taro-28/tanstack-table-search-params?tab=readme-ov-file#enable-disable)
     */
    enabled?: {
        [KEY in keyof State]?: boolean;
    };
};
type Props = {
    /**
     * search params state
     *
     * It is used to decode and create the `state` of the Tanstack Table.
     */
    query: Router["query"] | URLSearchParams;
    /**
     * It is used for calling `push`(or `replace`).
     */
    pathname: Router["pathname"];
} & ({
    /**
     * It is used to create a function like onChangeGlobalFilter that encodes state as a query parameter and performs a replace navigation.
     *
     * If both `push` and `replace` are provided, replace will be used.
     */
    replace: Router["navigate"];
} | {
    /**
     * It is used to create a function like onChangeGlobalFilter that encodes state as a query parameter and performs a push navigation.
     *
     * If both `push` and `replace` are provided, replace will be used.
     */
    push: Router["navigate"];
});
declare const useTableSearchParams: ({ pathname, query, ...props }: Props, options?: Options) => Returns;

export { type Options as O, PARAM_NAMES as P, type Query as Q, type Returns as R, type State as S, useTableSearchParams as u };