Scheduling infrastructure for absolutely everyone.
docs: add comprehensive DataTable usage guide (#24107)
Eunjae Leecc8a1290ee66
diff --git a/packages/features/data-table/GUIDE.md b/packages/features/data-table/GUIDE.mdnew file mode 100644index 00000000000..fb4be41df3f--- /dev/null+++ b/packages/features/data-table/GUIDE.md@@ -0,0 +1,1287 @@+# DataTable System Guide++A comprehensive guide to using Cal.com's DataTable system for building powerful, filterable, and paginated data tables.++## Table of Contents++1. [Overview](#overview)+2. [Quick Start](#quick-start)+3. [Core Components](#core-components)+4. [Filter System](#filter-system)+5. [Segment System](#segment-system)+6. [Pagination Modes](#pagination-modes)+7. [Toolbar Components](#toolbar-components)+8. [Advanced Usage](#advanced-usage)+9. [Real-world Examples](#real-world-examples)+10. [TypeScript Types Reference](#typescript-types-reference)+11. [Best Practices](#best-practices)++## Overview++The DataTable system is a comprehensive solution for displaying tabular data with advanced features including:++- **Advanced filtering** with 5 filter types and custom operators+- **Segment system** for saving and sharing filter configurations+- **Traditional pagination** with page-based navigation (recommended)+- **Column management** (sorting, resizing, visibility)+- **Bulk actions** and selection management+- **Full TypeScript support**+- **Alternative infinite scroll** mode (has known issues, use with caution)++### Architecture++The system consists of three main layers:++1. **DataTableProvider** - Context provider managing all table state+2. **DataTableWrapper** - UI wrapper handling pagination, toolbars, and loading states+3. **DataTable** - Core table component with optional virtualization++#### Data Flow Diagram++```+┌─────────────────────────────────────────────────────────────────┐+│ DataTableProvider │+│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │+│ │ Table State │ │ Filter State │ │ Segment State │ │+│ │ • pagination │ │ • columnFilters │ │ • activeSegment │ │+│ │ • sorting │ │ • searchTerm │ │ • userSegments │ │+│ │ • columnVis │ │ • activeFilters │ │ • systemSegments│ │+│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │+└─────────────────────────────────────────────────────────────────┘+ │+ ▼+┌─────────────────────────────────────────────────────────────────┐+│ DataTableWrapper │+│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │+│ │ Toolbar │ │ Data Table │ │ Pagination │ │+│ │ • SearchBar │ │ • Columns │ │ • PageControls │ │+│ │ • FilterBar │ │ • Rows │ │ • PageSize │ │+│ │ • Segments │ │ • Selection │ │ • TotalCount │ │+│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │+└─────────────────────────────────────────────────────────────────┘+ │+ ▼+┌─────────────────────────────────────────────────────────────────┐+│ Backend API │+│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │+│ │ Filter Processing│ │ Data Fetching │ │ Response Format │ │+│ │ • makeWhereClause│ │ • Prisma Query │ │ • data[] │ │+│ │ • makeSqlCondition│ │ • Raw SQL │ │ • totalCount │ │+│ │ • Column Mapping │ │ • Pagination │ │ • meta │ │+│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │+└─────────────────────────────────────────────────────────────────┘+```++#### Component Hierarchy++```+DataTableProvider (Context)+└── DataTableWrapper (UI Container)+ ├── Toolbar+ │ ├── ToolbarLeft+ │ │ ├── DataTableToolbar.SearchBar+ │ │ ├── DataTableFilters.FilterBar+ │ │ └── DataTableFilters.ColumnVisibilityButton+ │ └── ToolbarRight+ │ ├── DataTableFilters.ClearFiltersButton+ │ ├── DataTableSegment.SaveButton+ │ └── DataTableSegment.Select+ ├── DataTable (Core Table)+ │ ├── Table Header+ │ ├── Table Body (Virtualized/Standard)+ │ └── Selection Bar (Conditional)+ └── Pagination Controls+ ├── Page Navigation+ ├── Page Size Selector+ └── Total Count Display+```++## Quick Start++### Basic Setup++```tsx+import {+ DataTableProvider,+ DataTableWrapper,+ DataTableFilters,+ useDataTable,+ ColumnFilterType,+} from "@calcom/features/data-table";++// 1. Define your data type+type User = {+ id: number;+ name: string;+ email: string;+ role: string;+};++// 2. Create columns with filtering support+const columns = [+ {+ id: "name",+ header: "Name",+ accessorKey: "name",+ meta: {+ type: ColumnFilterType.TEXT,+ },+ },+ {+ id: "role",+ header: "Role",+ accessorKey: "role",+ meta: {+ type: ColumnFilterType.SINGLE_SELECT,+ },+ },+];++// 3. Setup the table+function UserTable() {+ const table = useReactTable({+ data: users,+ columns,+ // ... other table options+ });++ return (+ <DataTableProvider tableIdentifier="user-table">+ <DataTableWrapper+ table={table}+ paginationMode="standard"+ ToolbarLeft={+ <>+ <DataTableToolbar.SearchBar />+ <DataTableFilters.FilterBar table={table} />+ </>+ }+ ToolbarRight={+ <>+ <DataTableFilters.ClearFiltersButton />+ <DataTableSegment.SaveButton />+ <DataTableSegment.Select />+ </>+ }+ />+ </DataTableProvider>+ );+}+```++## Core Components++### DataTableProvider++The context provider that manages all table state including filters, sorting, pagination, and segments.++#### Props++```tsx+interface DataTableProviderProps {+ tableIdentifier?: string; // Unique identifier for the table+ children: React.ReactNode;+ useSegments?: UseSegments; // Custom segment hook+ defaultPageSize?: number; // Default: 10+ ctaContainerClassName?: string; // CSS class for CTA container+ segments?: FilterSegmentOutput[]; // Provided segments+ timeZone?: string; // Timezone for date filters+ preferredSegmentId?: SegmentIdentifier | null;+ systemSegments?: SystemFilterSegment[];+}+```++#### Context Values++The provider exposes comprehensive state management:++```tsx+type DataTableContextType = {+ // Filters+ activeFilters: ActiveFilters;+ addFilter: (columnId: string) => void;+ updateFilter: (columnId: string, value: FilterValue) => void;+ removeFilter: (columnId: string) => void;+ clearAll: (exclude?: string[]) => void;++ // Sorting+ sorting: SortingState;+ setSorting: OnChangeFn<SortingState>;++ // Column management+ columnVisibility: VisibilityState;+ setColumnVisibility: OnChangeFn<VisibilityState>;+ columnSizing: ColumnSizingState;+ setColumnSizing: OnChangeFn<ColumnSizingState>;++ // Pagination+ pageIndex: number;+ pageSize: number;+ setPageIndex: (pageIndex: number | null) => void;+ setPageSize: (pageSize: number | null) => void;+ offset: number;+ limit: number;++ // Segments+ segments: CombinedFilterSegment[];+ selectedSegment: CombinedFilterSegment | undefined;+ segmentId: SegmentIdentifier | null;+ setSegmentId: (id: SegmentIdentifier | null) => void;+ canSaveSegment: boolean;+ isSegmentEnabled: boolean;++ // Search+ searchTerm: string;+ setSearchTerm: (searchTerm: string | null) => void;+};+```++### DataTableWrapper++The main wrapper component that handles UI concerns, pagination, and toolbar layout.++#### Props++```tsx+type DataTableWrapperProps<TData> = {+ table: ReactTableType<TData>;+ testId?: string;+ bodyTestId?: string;+ isPending?: boolean;+ totalRowCount?: number;+ variant?: "default" | "compact";+ className?: string;+ containerClassName?: string;+ headerClassName?: string;+ rowClassName?: string;+ children?: React.ReactNode;+ tableContainerRef?: React.RefObject<HTMLDivElement>;+ onRowMouseclick?: (row: Row<TData>) => void;++ // Toolbar slots+ ToolbarLeft?: React.ReactNode;+ ToolbarRight?: React.ReactNode;++ // Loading states+ EmptyView?: React.ReactNode;+ LoaderView?: React.ReactNode;+} & (+ // Infinite pagination+ | {+ paginationMode: "infinite";+ hasNextPage: boolean;+ fetchNextPage: () => void;+ isFetching: boolean;+ }+ // Standard pagination+ | {+ paginationMode: "standard";+ hasNextPage?: never;+ fetchNextPage?: never;+ isFetching?: never;+ }+);+```++### DataTable++The core table component with column resizing and pinning support.++#### Key Features++- **Column resizing** - Drag to resize columns+- **Column pinning** - Pin columns to left/right+- **Responsive design** - Adapts to mobile screens+- **Accessibility** - Full keyboard navigation support+- **Optional virtualization** - Available for infinite mode (use with caution)++## Filter System++The DataTable supports 5 filter types with various operators and options.++### Filter Types++#### 1. Single Select Filter++```tsx+{+ type: ColumnFilterType.SINGLE_SELECT,+ options: [+ { label: "Admin", value: "admin" },+ { label: "User", value: "user" },+ { label: "Guest", value: "guest" },+ ]+}+```++#### 2. Multi Select Filter++```tsx+{+ type: ColumnFilterType.MULTI_SELECT,+ options: [+ { label: "Engineering", value: "eng", section: "Departments" },+ { label: "Marketing", value: "marketing", section: "Departments" },+ { label: "Sales", value: "sales", section: "Departments" },+ ]+}+```++#### 3. Text Filter++```tsx+{+ type: ColumnFilterType.TEXT,+ textOptions: {+ allowedOperators: ["contains", "equals", "startsWith"],+ placeholder: "Search names..."+ }+}+```++**Available operators:**+- `equals` - Exact match+- `notEquals` - Not equal+- `contains` - Contains substring+- `notContains` - Does not contain+- `startsWith` - Starts with+- `endsWith` - Ends with+- `isEmpty` - Is empty+- `isNotEmpty` - Is not empty++#### 4. Number Filter++```tsx+{+ type: ColumnFilterType.NUMBER+}+```++**Available operators:**+- `eq` - Equal to+- `neq` - Not equal to+- `gt` - Greater than+- `gte` - Greater than or equal+- `lt` - Less than+- `lte` - Less than or equal++#### 5. Date Range Filter++```tsx+{+ type: ColumnFilterType.DATE_RANGE,+ dateRangeOptions: {+ range: "past", // or "custom"+ convertToTimeZone: true+ }+}+```++### Column Filter Configuration++Add filtering to columns using the `meta` property:++```tsx+const columns = [+ {+ id: "status",+ header: "Status",+ accessorKey: "status",+ meta: {+ type: ColumnFilterType.SINGLE_SELECT,+ icon: "circle-dot", // Optional icon+ } as ColumnFilterMeta,+ },+ {+ id: "createdAt",+ header: "Created",+ accessorKey: "createdAt",+ meta: {+ type: ColumnFilterType.DATE_RANGE,+ dateRangeOptions: {+ range: "past",+ convertToTimeZone: true,+ },+ } as ColumnFilterMeta,+ },+];+```++### Faceted Filters with `getFacetedUniqueValues`++For select filters that need dynamic options based on data, use `getFacetedUniqueValues` in your table configuration:++```tsx+// In your table configuration+const table = useReactTable({+ // ... other options+ getFacetedUniqueValues: (_, columnId) => () => {+ switch (columnId) {+ case "teamId":+ return convertFacetedValuesToMap(+ teams.map(team => ({+ label: team.name,+ value: team.id+ }))+ );+ case "role":+ return convertFacetedValuesToMap([+ { label: "Admin", value: "admin" },+ { label: "Member", value: "member" }+ ]);+ default:+ return new Map();+ }+ }+});+```++**Custom Faceted Values Hook Example:**++From `apps/web/modules/bookings/hooks/useFacetedUniqueValues.ts`:++```tsx+export function useFacetedUniqueValues() {+ const eventTypes = useEventTypes();+ const { data: teams } = trpc.viewer.teams.list.useQuery();+ const { data: members } = trpc.viewer.teams.listSimpleMembers.useQuery();++ return useCallback(+ (_: Table<any>, columnId: string) => (): Map<FacetedValue, number> => {+ if (columnId === "eventTypeId") {+ return convertFacetedValuesToMap(eventTypes || []);+ } else if (columnId === "teamId") {+ return convertFacetedValuesToMap(+ (teams || []).map((team) => ({+ label: team.name,+ value: team.id,+ }))+ );+ } else if (columnId === "userId") {+ return convertFacetedValuesToMap(+ (members || [])+ .map((member) => ({+ label: member.name,+ value: member.id,+ }))+ .filter((option): option is { label: string; value: number } => Boolean(option.label))+ );+ }+ return new Map<FacetedValue, number>();+ },+ [eventTypes, teams, members]+ );+}+```++**Usage in Table Configuration:**++```tsx+// From packages/features/users/components/UserTable/UserListTable.tsx+const table = useReactTable({+ // ... other options+ getFacetedUniqueValues: (_, columnId) => () => {+ if (facetedTeamValues) {+ switch (columnId) {+ case "role":+ return convertFacetedValuesToMap(facetedTeamValues.roles);+ case "teamId":+ return convertFacetedValuesToMap(facetedTeamValues.teams);+ default:+ return new Map();+ }+ }+ return new Map();+ }+});+```++### Filter Components++#### FilterBar++Displays active filters and add filter button:++```tsx+<DataTableFilters.FilterBar table={table} />+```++#### Individual Filter Components++```tsx+// Add filter button+<DataTableFilters.AddFilterButton table={table} />++// Active filters display+<DataTableFilters.ActiveFilters table={table} />++// Clear all filters+<DataTableFilters.ClearFiltersButton />++// Column visibility toggle+<DataTableFilters.ColumnVisibilityButton table={table} />+```++## Segment System++Segments allow users to save and share filter configurations. There are two types:++**Important:** Filter segments are only enabled when you pass the `useSegments` prop to `DataTableProvider`:++```tsx+<DataTableProvider+ tableIdentifier="users"+ useSegments={useSegments} // Required to enable segments+>+ {/* Your table content */}+</DataTableProvider>+```++Without the `useSegments` prop, segment functionality will be disabled and segment-related components will not be available.++### System Segments++Predefined segments created by developers:++```tsx+const systemSegments: SystemFilterSegment[] = [+ {+ id: "active-users",+ name: "Active Users",+ type: "system",+ activeFilters: [+ {+ f: "status",+ v: {+ type: ColumnFilterType.SINGLE_SELECT,+ data: "active"+ }+ }+ ],+ sorting: [{ id: "lastLogin", desc: true }],+ }+];++<DataTableProvider+ systemSegments={systemSegments}+ tableIdentifier="user-table"+>+ {/* ... */}+</DataTableProvider>+```++### User Segments++Segments saved by users with personal or team scope:++```tsx+// Personal segment (scope: "USER")+// Team segment (scope: "TEAM")+```++### Segment Components++```tsx+// Segment selector dropdown+<DataTableSegment.Select />++// Save current state as segment+<DataTableSegment.SaveButton />++// Segment management (rename, duplicate, delete)+// Available in the segment dropdown submenu+```++### Segment Permissions++- **Personal segments**: Only visible to the creator+- **Team segments**: Visible to all team members+- **System segments**: Visible to all users+- **Admin actions**: Rename/delete require admin/owner permissions++## Pagination Modes++### Standard Pagination (Recommended)++Traditional page-based pagination is the recommended approach:++```tsx+<DataTableWrapper+ paginationMode="standard"+ totalRowCount={totalCount}+ table={table}+/>+```++**Features:**+- Page numbers and navigation+- Configurable page sizes+- Total count display+- Reliable performance+- Better user experience+- No virtualization issues++**Why Standard Mode is Preferred:**+Standard pagination provides a more predictable and stable user experience. It avoids the complexity and potential issues associated with virtualized infinite scrolling.++### Infinite Pagination (Use with Caution)++Alternative infinite scroll mode with known limitations:++```tsx+<DataTableWrapper+ paginationMode="infinite"+ hasNextPage={hasNextPage}+ fetchNextPage={fetchNextPage}+ isFetching={isFetching}+ table={table}+/>+```++**Features:**+- Automatic loading on scroll+- Virtualized rendering+- Fixed container height (80dvh)++**Known Issues:**+- Virtualized infinite loading has several problems+- Can cause performance and UX issues+- Standard mode was introduced to address these problems+- Use only when absolutely necessary and with thorough testing++## Toolbar Components++### DataTableToolbar++Container and utility components for table toolbars:++```tsx+// Toolbar container+<DataTableToolbar.Root>+ <DataTableToolbar.SearchBar />+ <DataTableToolbar.CTA color="primary" StartIcon="plus">+ Add User+ </DataTableToolbar.CTA>+</DataTableToolbar.Root>++// Search input with debounced updates+<DataTableToolbar.SearchBar className="max-w-48" />++// Clear filters button (auto-hides when no filters)+<DataTableToolbar.ClearFiltersButton />++// Custom action button+<DataTableToolbar.CTA+ color="secondary"+ StartIcon="download"+ onClick={handleExport}+>+ Export+</DataTableToolbar.CTA>+```++### DataTableSelectionBar++For bulk actions when rows are selected:++```tsx+{numberOfSelectedRows > 0 && (+ <DataTableSelectionBar.Root>+ <p>{t("number_selected", { count: numberOfSelectedRows })}</p>++ <DataTableSelectionBar.Button+ color="destructive"+ icon="trash-2"+ onClick={handleBulkDelete}+ >+ Delete Selected+ </DataTableSelectionBar.Button>+ </DataTableSelectionBar.Root>+)}+```++## Advanced Usage++### Server-Side Operations++The DataTable system is designed for **server-side filtering, sorting, and pagination** with standard pagination. This approach is necessary because we only fetch a limited number of items per page, unlike the previous infinite scrolling approach that cached large amounts of data and could filter on the client side.++#### Basic Server-Side Pattern++```tsx+// Get current table state for API calls+const { limit, offset, sorting } = useDataTable();+const columnFilters = useColumnFilters();++// Use in your API call+const { data } = trpc.users.list.useQuery({+ limit,+ offset,+ sorting,+ filters: columnFilters+});+```++#### Prisma Where Clause Construction++For Prisma-based backends, extract individual filters and build typed where conditions:++```tsx+// From packages/trpc/server/routers/viewer/organizations/listMembers.handler.ts+const roleFilter = filters.find((filter) => filter.id === "role") as+ | TypedColumnFilter<ColumnFilterType.MULTI_SELECT>+ | undefined;+const teamFilter = filters.find((filter) => filter.id === "teams") as+ | TypedColumnFilter<ColumnFilterType.MULTI_SELECT>+ | undefined;+const lastActiveAtFilter = filters.find((filter) => filter.id === "lastActiveAt") as+ | TypedColumnFilter<ColumnFilterType.DATE_RANGE>+ | undefined;++const whereClause: Prisma.MembershipWhereInput = {+ user: {+ ...(teamFilter && {+ teams: {+ some: {+ team: makeWhereClause({+ columnName: "name",+ filterValue: teamFilter.value,+ }),+ },+ },+ }),+ ...(lastActiveAtFilter &&+ makeWhereClause({+ columnName: "lastActiveAt",+ filterValue: lastActiveAtFilter.value,+ })),+ },+ teamId: organizationId,+ ...(roleFilter && makeWhereClause({+ columnName: "role",+ filterValue: roleFilter.value,+ })),+};+```++#### Raw SQL Optimization++For performance-critical queries, use raw SQL with `makeSqlCondition`:++```tsx+// From packages/lib/server/service/InsightsRoutingBaseService.ts+async getFilterConditions(): Promise<Prisma.Sql | null> {+ const conditions: Prisma.Sql[] = [];+ const columnFilters = this.filters.columnFilters || [];++ // Convert columnFilters array to object for easier access+ const filtersMap = columnFilters.reduce((acc, filter) => {+ acc[filter.id] = filter;+ return acc;+ }, {} as Record<string, TypedColumnFilter<ColumnFilterType>>);++ // Extract booking status order filter+ const bookingStatusOrder = filtersMap["bookingStatusOrder"];+ if (bookingStatusOrder && isMultiSelectFilterValue(bookingStatusOrder.value)) {+ const statusCondition = makeSqlCondition(bookingStatusOrder.value);+ if (statusCondition) {+ conditions.push(Prisma.sql`rfrd."bookingStatusOrder" ${statusCondition}`);+ }+ }++ // Extract booking UID filter+ const bookingUid = filtersMap["bookingUid"];+ if (bookingUid && isTextFilterValue(bookingUid.value)) {+ const uidCondition = makeSqlCondition(bookingUid.value);+ if (uidCondition) {+ conditions.push(Prisma.sql`rfrd."bookingUid" ${uidCondition}`);+ }+ }++ // Join all conditions with AND+ return conditions.reduce((acc, condition, index) => {+ if (index === 0) return condition;+ return Prisma.sql`(${acc}) AND (${condition})`;+ });+}+```++#### Advanced Parameter Manipulation++For complex cases where you need to manipulate filter data before sending to the backend, extract the logic into a separate hook:++```tsx+// packages/features/insights/hooks/useInsightsRoutingParameters.ts+export function useInsightsRoutingParameters() {+ const { scope, selectedTeamId } = useInsightsOrgTeams();++ // Get date range filter and manipulate it+ const createdAtRange = useFilterValue("createdAt", ZDateRangeFilterValue)?.data;+ const startDate = useChangeTimeZoneWithPreservedLocalTime(+ useMemo(() => {+ return dayjs(createdAtRange?.startDate ?? getDefaultStartDate().toISOString())+ .startOf("day")+ .toISOString();+ }, [createdAtRange?.startDate])+ );++ // Get other column filters excluding the manipulated ones+ const columnFilters = useColumnFilters({+ exclude: ["createdAt"],+ });++ return {+ scope,+ selectedTeamId,+ startDate,+ endDate,+ columnFilters,+ };+}+```++#### Key Hooks for Server-Side Integration++- **`useColumnFilters()`** - Get applied filters for backend requests+- **`useDataTable()`** - Get `limit`, `offset`, `sorting` for pagination+- **`useFilterValue(columnId, schema)`** - Get specific filter value with validation+- **Custom parameter hooks** - Extract complex manipulation logic++#### Server Utility Functions++The DataTable system provides utility functions for both Prisma and raw SQL approaches:++- **`makeWhereClause()`** - Converts filter values to Prisma where clause objects+- **`makeSqlCondition()`** - Converts filter values to raw SQL conditions+- **`makeOrderBy()`** - Converts sorting state to Prisma orderBy format++### Custom Hooks++#### useDataTable++Access the DataTable context:++```tsx+const {+ activeFilters,+ sorting,+ columnVisibility,+ pageIndex,+ pageSize,+ searchTerm,+ selectedSegment,+} = useDataTable();+```++#### useColumnFilters++Get processed column filters for API calls:++```tsx+const columnFilters = useColumnFilters();+// Returns: ColumnFilter[] ready for backend consumption++// With exclusions (useful when manipulating specific filters)+const columnFilters = useColumnFilters({+ exclude: ["createdAt", "dateRange"]+});+```++#### useFilterableColumns++Extract filterable columns from table definition:++```tsx+const filterableColumns = useFilterableColumns(table);+```++### Custom Filter Components++Create custom filter implementations:++```tsx+function CustomStatusFilter({ column }: { column: Column<any> }) {+ const { updateFilter } = useDataTable();++ return (+ <Select+ onValueChange={(value) =>+ updateFilter(column.id, {+ type: ColumnFilterType.SINGLE_SELECT,+ data: value+ })+ }+ >+ {/* Custom filter UI */}+ </Select>+ );+}+```++### Portal Integration++Use portals for toolbar actions:++```tsx+const { ctaContainerRef } = useDataTable();++{ctaContainerRef.current && createPortal(+ <div className="flex gap-2">+ <Button>Custom Action</Button>+ </div>,+ ctaContainerRef.current+)}+```++## Real-world Examples++### Example 1: User Management Table++From `packages/features/users/components/UserTable/UserListTable.tsx`:++```tsx+<DataTableWrapper<UserTableUser>+ testId="user-list-data-table"+ table={table}+ isPending={isPending}+ totalRowCount={data?.meta?.totalRowCount}+ paginationMode="standard"+ ToolbarLeft={+ <>+ <DataTableToolbar.SearchBar />+ <DataTableFilters.ColumnVisibilityButton table={table} />+ <DataTableFilters.FilterBar table={table} />+ </>+ }+ ToolbarRight={+ <>+ <DataTableFilters.ClearFiltersButton />+ <DataTableSegment.SaveButton />+ <DataTableSegment.Select />+ </>+ }+>+ {/* Selection bar for bulk actions */}+ {numberOfSelectedRows > 0 && (+ <DataTableSelectionBar.Root>+ <p>{t("number_selected", { count: numberOfSelectedRows })}</p>+ <DeleteBulkUsers+ users={table.getSelectedRowModel().flatRows.map(row => row.original)}+ onRemove={() => table.toggleAllPageRowsSelected(false)}+ />+ </DataTableSelectionBar.Root>+ )}+</DataTableWrapper>+```++### Example 2: Bookings List++From `apps/web/modules/bookings/views/bookings-listing-view.tsx`:++```tsx+<DataTableWrapper+ className="mb-6"+ tableContainerRef={tableContainerRef}+ table={table}+ testId={`${status}-bookings`}+ bodyTestId="bookings"+ headerClassName="hidden"+ isPending={query.isPending}+ totalRowCount={query.data?.totalCount}+ variant="compact"+ paginationMode="standard"+ ToolbarLeft={+ <DataTableFilters.FilterBar table={table} />+ }+ ToolbarRight={+ <>+ <DataTableFilters.ClearFiltersButton />+ <DataTableSegment.SaveButton />+ <DataTableSegment.Select />+ </>+ }+ LoaderView={<SkeletonLoader />}+ EmptyView={+ <EmptyScreen+ Icon="calendar"+ headline={t("no_status_bookings_yet", { status: t(status).toLowerCase() })}+ description={t("no_status_bookings_yet_description")}+ />+ }+/>+```++### Example 3: Team Member List with Infinite Scroll++From `packages/features/ee/teams/components/MemberList.tsx`:++```tsx+<DataTableWrapper+ testId="team-member-list-container"+ table={table}+ tableContainerRef={tableContainerRef}+ isPending={isPending}+ paginationMode="infinite"+ hasNextPage={hasNextPage}+ fetchNextPage={fetchNextPage}+ isFetching={isFetching}+ ToolbarLeft={+ <>+ <DataTableToolbar.SearchBar />+ <DataTableFilters.FilterBar table={table} />+ </>+ }+ ToolbarRight={+ <>+ <DataTableFilters.ClearFiltersButton />+ <DataTableSegment.SaveButton />+ <DataTableSegment.Select />+ </>+ }+>+ {/* Bulk selection and actions */}+ {numberOfSelectedRows > 0 && (+ <DataTableSelectionBar.Root>+ <TeamListBulkAction table={table} />+ <MassAssignAttributesBulkAction table={table} filters={columnFilters} />+ </DataTableSelectionBar.Root>+ )}+</DataTableWrapper>+```++## TypeScript Types Reference++### Core Types++```tsx+// Filter value types+type FilterValue =+ | SingleSelectFilterValue+ | MultiSelectFilterValue+ | TextFilterValue+ | NumberFilterValue+ | DateRangeFilterValue;++// Active filter structure+type ActiveFilter = {+ f: string; // field/column ID+ v?: FilterValue; // filter value+};++// Segment types+type SegmentIdentifier =+ | { id: string; type: "system" }+ | { id: number; type: "user" };++// Column filter metadata+type ColumnFilterMeta = {+ type: ColumnFilterType;+ icon?: IconName;+ dateRangeOptions?: DateRangeFilterOptions;+ textOptions?: TextFilterOptions;+};+```++### Filter Value Schemas++```tsx+// Single select+type SingleSelectFilterValue = {+ type: ColumnFilterType.SINGLE_SELECT;+ data: string | number;+};++// Multi select+type MultiSelectFilterValue = {+ type: ColumnFilterType.MULTI_SELECT;+ data: Array<string | number>;+};++// Text filter+type TextFilterValue = {+ type: ColumnFilterType.TEXT;+ data: {+ operator: TextFilterOperator;+ operand: string;+ };+};++// Number filter+type NumberFilterValue = {+ type: ColumnFilterType.NUMBER;+ data: {+ operator: NumberFilterOperator;+ operand: number;+ };+};++// Date range filter+type DateRangeFilterValue = {+ type: ColumnFilterType.DATE_RANGE;+ data: {+ startDate: string | null;+ endDate: string | null;+ preset: string;+ };+};+```++### Segment Types++```tsx+// System segment (predefined)+type SystemFilterSegment = {+ id: string;+ name: string;+ type: "system";+ activeFilters: ActiveFilters;+ sorting?: SortingState;+ columnVisibility?: Record<string, boolean>;+ columnSizing?: Record<string, number>;+ perPage?: number;+ searchTerm?: string | null;+};++// User segment (saved by users)+type UserFilterSegment = FilterSegmentOutput & {+ type: "user";+};++// Combined segment type+type CombinedFilterSegment = SystemFilterSegmentInternal | UserFilterSegment;+```++## Best Practices++### Performance++1. **Use standard pagination** for most use cases (recommended)+2. **Implement proper memoization** for column definitions+3. **Debounce search inputs** (handled automatically by DataTableToolbar.SearchBar)+4. **Consider infinite mode only for specific cases** where traditional pagination isn't suitable, but be aware of potential issues++### State Management++1. **Provide unique tableIdentifier** for each table instance+2. **Use segments** for complex filter combinations+3. **Persist user preferences** via the segment system+4. **Clear filters appropriately** when changing contexts++### User Experience++1. **Provide loading states** with LoaderView and EmptyView+2. **Use standard pagination** for consistent user experience+3. **Include search functionality** for text-heavy data+4. **Implement bulk actions** for management interfaces+5. **Show filter counts** and active filter indicators++### Accessibility++1. **Use semantic HTML** (handled by components)+2. **Provide proper ARIA labels** for custom filters+3. **Support keyboard navigation** (built-in)+4. **Test with screen readers**++### Code Organization++```tsx+// ✅ Good: Memoize column definitions+const columns = useMemo(() => [+ {+ id: "name",+ header: "Name",+ accessorKey: "name",+ meta: { type: ColumnFilterType.TEXT },+ },+], []);++// ✅ Good: Extract filter logic+const useUserFilters = () => {+ const columnFilters = useColumnFilters();+ return useMemo(() =>+ transformFiltersForAPI(columnFilters),+ [columnFilters]+ );+};++// ✅ Good: Separate concerns+function UserTableContainer() {+ const filters = useUserFilters();+ const { data, isPending } = useUsers(filters);++ return (+ <DataTableProvider tableIdentifier="users">+ <UserTable data={data} isPending={isPending} />+ </DataTableProvider>+ );+}+```++### Common Patterns++#### Filter Integration with API++```tsx+function useTableData() {+ const columnFilters = useColumnFilters();+ const { sorting, pageIndex, pageSize, searchTerm } = useDataTable();++ const queryParams = useMemo(() => ({+ filters: columnFilters,+ sorting,+ page: pageIndex,+ limit: pageSize,+ search: searchTerm,+ }), [columnFilters, sorting, pageIndex, pageSize, searchTerm]);++ return useQuery({+ queryKey: ['table-data', queryParams],+ queryFn: () => fetchData(queryParams),+ });+}+```++#### Custom Filter Options++```tsx+function useStatusFilterOptions() {+ const { data: statuses } = useStatuses();++ return useMemo(() =>+ statuses?.map(status => ({+ label: status.name,+ value: status.id,+ section: status.category,+ })) || [],+ [statuses]+ );+}+```++#### Segment Presets++```tsx+const BOOKING_SEGMENTS: SystemFilterSegment[] = [+ {+ id: "upcoming",+ name: "Upcoming",+ type: "system",+ activeFilters: [+ {+ f: "status",+ v: { type: ColumnFilterType.SINGLE_SELECT, data: "confirmed" }+ },+ {+ f: "startTime",+ v: {+ type: ColumnFilterType.DATE_RANGE,+ data: { preset: "future", startDate: null, endDate: null }+ }+ }+ ],+ sorting: [{ id: "startTime", desc: false }],+ },+];+```++This guide covers the complete DataTable system. For specific implementation details, refer to the source files in `packages/features/data-table/` and the usage examples throughout the Cal.com codebase.