@itwin/itwinui-react/esm/core/Table/Table.d.ts

A react component library for iTwinUI

import * as React from 'react';
import type { CellProps, TableOptions, Row, TableState } from '../../react-table/react-table.js';
import type { CommonProps } from '../../utils/index.js';
import type { TableFilterValue } from './filters/index.js';
export declare const tableResizeStartAction = "tableResizeStart";
export declare const iuiId: unique symbol;
export type TablePaginatorRendererProps = {
    /**
     * The zero-based index of the current page.
     */
    currentPage: number;
    /**
     * Total number of rows.
     */
    totalRowsCount: number;
    /**
     * Number of rows per page.
     */
    pageSize: number;
    /**
     * Callback when page is changed.
     */
    onPageChange: (page: number) => void;
    /**
     * Callback when page size is changed.
     */
    onPageSizeChange: (size: number) => void;
    /**
     * Modify the size of the pagination (adjusts the elements size).
     * @default 'default' if Table density is `default` else `small`
     */
    size?: 'default' | 'small';
    /**
     * Flag whether data is still loading and total rows count is not known.
     * @default false
     */
    isLoading?: boolean;
    /**
     * Total number of rows selected (for mutli-selection mode only)
     */
    totalSelectedRowsCount?: number;
};
/**
 * Table props.
 * columns and data must be memoized.
 */
export type TableProps<T extends Record<string, unknown> = Record<string, unknown>> = Omit<TableOptions<T>, 'disableSortBy'> & Omit<React.ComponentPropsWithoutRef<'div'>, 'role' | 'onSelect'> & {
    /**
     * Flag whether data is loading.
     * @default false
     */
    isLoading?: boolean;
    /**
     * Content shown when there is no data.
     */
    emptyTableContent: React.ReactNode;
    /**
     * Flag whether table rows can be selectable.
     * @default false
     */
    isSelectable?: boolean;
    /**
     * Handler for rows selection. Must be memoized.
     * This is triggered only by user initiated actions (i.e. data change will not call it).
     */
    onSelect?: (selectedData: T[] | undefined, tableState?: TableState<T>) => void;
    /**
     * Handler for when a row is clicked. Must be memoized.
     */
    onRowClick?: (event: React.MouseEvent, row: Row<T>) => void;
    /**
     * Modify the selection mode of the table.
     * The column with checkboxes will not be present with 'single' selection mode.
     * @default 'multi'
     */
    selectionMode?: 'multi' | 'single';
    /**
     * Flag whether table columns can be sortable.
     * @default false
     */
    isSortable?: boolean;
    /**
     * Callback function when sort changes.
     * Use with `manualSortBy` to handle sorting yourself e.g. sort in server-side.
     * Must be memoized.
     */
    onSort?: (state: TableState<T>) => void;
    /**
     * Callback function when scroll reaches bottom. Can be used for lazy-loading the data.
     */
    onBottomReached?: () => void;
    /**
     * Callback function when row is in viewport.
     */
    onRowInViewport?: (rowData: T) => void;
    /**
     * Margin in pixels when row is considered to be already in viewport. Used for `onBottomReached` and `onRowInViewport`.
     * @default 300
     */
    intersectionMargin?: number;
    /**
     * A function that will be used for rendering a component for each row if that row is expanded.
     * Component will be placed right after the row. Can return false/null if row should not be expandable.
     */
    subComponent?: (row: Row<T>) => React.ReactNode;
    /**
     * A function used for overriding default expander cell. `subComponent` must be present.
     * Make sure to trigger `cellProps.row.toggleRowExpanded()`.
     */
    expanderCell?: (cellProps: CellProps<T>) => React.ReactNode;
    /**
     * Handler for row expand events. Will trigger when expanding and collapsing rows.
     */
    onExpand?: (expandedData: T[] | undefined, tableState?: TableState<T>) => void;
    /**
     * Callback function when filters change.
     * Use with `manualFilters` to handle filtering yourself e.g. filter in server-side.
     * Must be memoized.
     */
    onFilter?: (filters: TableFilterValue<T>[], state: TableState<T>, filteredData?: Row<T>[]) => void;
    /**
     * Value used for global filtering.
     * Use with `globalFilter` and/or `manualGlobalFilter` to handle filtering yourself e.g. filter in server-side.
     * Must be memoized.
     */
    globalFilterValue?: unknown;
    /**
     * Content shown when there is no data after filtering.
     */
    emptyFilteredTableContent?: React.ReactNode;
    /**
     * Function that should return true if a row is disabled (i.e. cannot be selected or expanded).
     * If not specified, all rows are enabled.
     */
    isRowDisabled?: (rowData: T) => boolean;
    /**
     * Function that should return custom props passed to the each row.
     * Must be memoized.
     */
    rowProps?: (row: Row<T>) => React.ComponentPropsWithRef<'div'> & {
        status?: 'positive' | 'warning' | 'negative';
        isLoading?: boolean;
    };
    /**
     * Modify the density of the table (adjusts the row height).
     * @default 'default'
     */
    density?: 'default' | 'condensed' | 'extra-condensed';
    /**
     * Flag whether to select a row when clicked anywhere inside of it.
     * @default true
     */
    selectRowOnClick?: boolean;
    /**
     * Function that takes `TablePaginatorRendererProps` as an argument and returns pagination component.
     *
     * Recommended to use `TablePaginator`. Passing `props` to `TablePaginator` handles all state management and is enough for basic use-cases.
     * @example
     * (props: TablePaginatorRendererProps) => (
     *   <TablePaginator {...props} />
     * )
     */
    paginatorRenderer?: (props: TablePaginatorRendererProps) => React.ReactNode;
    /**
     * Number of rows per page.
     * @default 25
     */
    pageSize?: number;
    /**
     * Flag whether columns are resizable.
     * In order to disable resizing for specific column, set `disableResizing: true` for that column.
     * @default false
     */
    isResizable?: boolean;
    /**
     * Style of the table.
     * @default 'default'
     */
    styleType?: 'default' | 'zebra-rows';
    /**
     * Virtualization is used for the scrollable table body.
     * Height on the table is required for virtualization to work.
     * @example
     * <Table enableVirtualization style={{height: 400}} {...} />
     * @default false
     * @beta
     */
    enableVirtualization?: boolean;
    /**
     * Flag whether columns can be reordered.
     * @default false
     */
    enableColumnReordering?: boolean;
    /**
     * Passes props to Table header wrapper.
     */
    headerWrapperProps?: React.ComponentProps<'div'>;
    /**
     * Passes props to Table header.
     */
    headerProps?: React.ComponentProps<'div'>;
    /**
     * Passes custom props to Table body.
     */
    bodyProps?: React.ComponentProps<'div'>;
    /**
     * Passes props to the `role="table"` element within the wrapper.
     *
     * - If `tableProps` or `role` is passed to `Table`, all ARIA attributes passed to `Table` will be passed to the wrapper.
     * - Else, all ARIA attributes will be passed to the inner element with `role="table"`.
     */
    tableProps?: React.ComponentProps<'div'>;
    /**
     * Passes custom props to empty table.
     */
    emptyTableContentProps?: React.ComponentProps<'div'>;
    /**
     * Function that returns index of the row that you want to scroll to.
     *
     * When using with lazy-loading table, you need to take care that row is already loaded.
     * It doesn't work with paginated tables.
     * @beta
     * @example
     * <Table
     *   scrollToRow={React.useCallback(
     *     (rows, data) => rows.findIndex((row) => row.original === data[250]),
     *     []
     *   )}
     *   {...restProps}
     * />
     * @example
     * <Table
     *   scrollToRow={React.useCallback(
     *     (rows, data) => rows.findIndex((row) => row.original.id === data[250].id),
     *     []
     *   )}
     *   {...restProps}
     * />
     */
    scrollToRow?: (rows: Row<T>[], data: T[]) => number;
    /**
     * Caption for the table.
     *
     * Although optional for backward compatibility, it is **recommended** to use it for accessibility purposes.
     *
     * @default "Table"
     */
    caption?: string;
    /**
     * If `tableProps` or `role` is passed to `Table`, all ARIA attributes passed to `Table` will be passed to the wrapper.
     * Else, all ARIA attributes will be passed to the inner element with `role="table"`.
     */
    role?: React.AriaRole;
} & Omit<CommonProps, 'title'>;
/**
 * Table based on [react-table](https://react-table.tanstack.com/docs/api/overview).
 *
 * **Note**: If `tableProps` or `role` is passed to `Table`, all ARIA attributes passed to `Table` will be passed to the wrapper.
 * Else, all ARIA attributes will be passed to the inner element with `role="table"`.
 *
 * ---
 *
 * @example
 * const columns = React.useMemo(() => [
 *   {
 *     id: 'name',
 *     Header: 'Name',
 *     accessor: 'name',
 *     width: 90,
 *   },
 *   {
 *     id: 'description',
 *     Header: 'description',
 *     accessor: 'description',
 *     maxWidth: 200,
 *   },
 *   {
 *     id: 'view',
 *     Header: 'view',
 *     Cell: () => {
 *       return <span onClick={onViewClick}>View</span>
 *     },
 *   },
 * ], [onViewClick])
 * const data = [
 *  { name: 'Name1', description: 'Description1' },
 *  { name: 'Name2', description: 'Description2' },
 *  { name: 'Name3', description: 'Description3' },
 * ]
 * <Table
 *   columns={columns}
 *   data={data}
 *   emptyTableContent='No data.'
 *   isLoading={false}
 *   isSortable={true}
 * />
 */
export declare const Table: {
    <T extends Record<string, unknown> = Record<string, unknown>>(props: TableProps<T>): React.JSX.Element;
    displayName: string;
};