0
# Pagination
1

2
Built-in pagination system with configurable page sizes and navigation controls for managing large datasets efficiently.
3

4
## Capabilities
5

6
### Page Navigation
7

8
Methods for controlling current page position and navigation.
9

10
```javascript { .api }
11
/**
12
 * Set current page number
13
 * @param page - Page number to navigate to (1-based)
14
 * @returns Promise resolving when page loads
15
 */
16
setPage(page: number): Promise<void>;
17

18
/**
19
 * Navigate to page containing specific row
20
 * @param row - Row index to find and navigate to
21
 * @returns Promise resolving when page loads
22
 */
23
setPageToRow(row: any): Promise<void>;
24

25
/**
26
 * Get current page number
27
 * @returns Current page number (1-based)
28
 */
29
getPage(): number;
30

31
/**
32
 * Get maximum page number
33
 * @returns Total number of pages
34
 */
35
getPageMax(): number;
36

37
/**
38
 * Navigate to previous page
39
 * @returns Promise resolving to true if navigation occurred, false if already at first page
40
 */
41
previousPage(): Promise<boolean>;
42

43
/**
44
 * Navigate to next page  
45
 * @returns Promise resolving to true if navigation occurred, false if already at last page
46
 */
47
nextPage(): Promise<boolean>;
48
```
49

50
**Usage Examples:**
51

52
```javascript
53
// Basic page navigation
54
await table.setPage(3); // Go to page 3
55
console.log("Current page:", table.getPage());
56
console.log("Total pages:", table.getPageMax());
57

58
// Navigate by row
59
await table.setPageToRow(150); // Go to page containing row 150
60

61
// Sequential navigation
62
if (await table.nextPage()) {
63
  console.log("Moved to next page");
64
} else {
65
  console.log("Already at last page");
66
}
67

68
await table.previousPage();
69
```
70

71
### Page Size Control
72

73
Configure and modify the number of rows displayed per page.
74

75
```javascript { .api }
76
/**
77
 * Set number of rows per page
78
 * @param size - Number of rows per page
79
 */
80
setPageSize(size: number): void;
81

82
/**
83
 * Get current page size
84
 * @returns Number of rows per page
85
 */
86
getPageSize(): number;
87
```
88

89
**Usage Examples:**
90

91
```javascript
92
// Change page size
93
table.setPageSize(50);
94
console.log("Rows per page:", table.getPageSize());
95

96
// Dynamic page size based on screen size
97
function adjustPageSize() {
98
  const screenHeight = window.innerHeight;
99
  const rowHeight = 35; // Approximate row height
100
  const headerHeight = 100; // Header and controls
101
  const maxRows = Math.floor((screenHeight - headerHeight) / rowHeight);
102
  
103
  table.setPageSize(Math.max(10, maxRows));
104
}
105

106
window.addEventListener("resize", adjustPageSize);
107
adjustPageSize();
108
```
109

110
## Pagination Configuration
111

112
### Basic Pagination Setup
113

114
Enable and configure pagination behavior during table initialization.
115

116
```javascript { .api }
117
interface PaginationConfig {
118
  /** Enable pagination */
119
  pagination?: boolean | "local" | "remote";
120
  /** Pagination mode */
121
  paginationMode?: "local" | "remote";
122
  /** Default page size */
123
  paginationSize?: number;
124
  /** Show page size selector */
125
  paginationSizeSelector?: boolean | number[];
126
  /** Page size selector options */
127
  paginationSizeOptions?: number[];
128
  /** Custom pagination element */
129
  paginationElement?: string | HTMLElement;
130
  /** Add rows to current page or table */
131
  paginationAddRow?: "table" | "page";
132
  /** Number of page buttons to show */
133
  paginationButtonCount?: number;
134
  /** Initial page to display */
135
  paginationInitialPage?: number;
136
}
137
```
138

139
**Usage Examples:**
140

141
```javascript
142
// Basic pagination setup
143
const paginatedTable = new Tabulator("#paginated-table", {
144
  data: largeDataset,
145
  columns: columnDefinitions,
146
  pagination: true,
147
  paginationMode: "local",
148
  paginationSize: 25,
149
  paginationSizeSelector: [10, 25, 50, 100],
150
  paginationButtonCount: 5
151
});
152

153
// Remote pagination for server-side data
154
const remotePaginatedTable = new Tabulator("#remote-table", {
155
  ajaxURL: "/api/data",
156
  pagination: "remote",
157
  paginationMode: "remote", 
158
  paginationSize: 20,
159
  paginationSizeSelector: true,
160
  ajaxParams: { version: "2.0" }
161
});
162

163
// Custom pagination element
164
const customPaginationTable = new Tabulator("#custom-pagination", {
165
  data: tableData,
166
  columns: columnDefinitions,
167
  pagination: true,
168
  paginationElement: "#custom-pagination-controls",
169
  paginationSize: 15
170
});
171
```
172

173
### Advanced Pagination Options
174

175
```javascript { .api }
176
interface AdvancedPaginationConfig {
177
  /** Counter element selector */
178
  paginationCounter?: string | HTMLElement | Function;
179
  /** Counter text template */
180
  paginationCounterElement?: string | HTMLElement;
181
  /** Data received callback for remote pagination */
182
  paginationDataReceived?: { [key: string]: string };
183
  /** Data sent callback for remote pagination */
184
  paginationDataSent?: { [key: string]: string };
185
  /** Show first/last page buttons */
186
  paginationFirstLastButtons?: boolean;
187
  /** Pagination info display */
188
  paginationInfo?: boolean | Function;
189
}
190
```
191

192
## Remote Pagination
193

194
### Server-side Pagination
195

196
Configure table to work with server-side pagination systems.
197

198
```javascript { .api }
199
interface RemotePaginationConfig {
200
  /** Remote pagination mode */
201
  paginationMode: "remote";
202
  /** AJAX URL for data requests */
203
  ajaxURL: string;
204
  /** Parameters sent with pagination requests */
205
  paginationDataSent?: {
206
    page?: string;      // Page number parameter name (default: "page")
207
    size?: string;      // Page size parameter name (default: "size") 
208
    sorters?: string;   // Sorters parameter name (default: "sort")
209
    filters?: string;   // Filters parameter name (default: "filter")
210
  };
211
  /** Expected response data structure */
212
  paginationDataReceived?: {
213
    data?: string;        // Data array property (default: "data")
214
    last_page?: string;   // Total pages property (default: "last_page")
215
    total?: string;       // Total records property (default: "total")
216
  };
217
}
218
```
219

220
**Usage Examples:**
221

222
```javascript
223
// Server-side pagination with custom parameters
224
const serverPaginatedTable = new Tabulator("#server-table", {
225
  ajaxURL: "/api/users",
226
  pagination: "remote",
227
  paginationMode: "remote",
228
  paginationSize: 20,
229
  paginationDataSent: {
230
    page: "pageNumber",
231
    size: "recordsPerPage", 
232
    sorters: "sortBy",
233
    filters: "filterBy"
234
  },
235
  paginationDataReceived: {
236
    data: "users",
237
    last_page: "totalPages",  
238
    total: "totalRecords"
239
  },
240
  ajaxResponse: function(url, params, response) {
241
    // Transform server response if needed
242
    return {
243
      data: response.users,
244
      last_page: response.totalPages,
245
      total: response.totalRecords
246
    };
247
  }
248
});
249

250
// Handle server errors
251
serverPaginatedTable.on("dataLoadError", function(error) {
252
  console.error("Pagination data load failed:", error);
253
  showErrorMessage("Failed to load data. Please try again.");
254
});
255
```
256

257
## Pagination Events
258

259
### Page Change Events
260

261
Events triggered during pagination operations.
262

263
```javascript { .api }
264
interface PaginationEvents {
265
  /** Fired when page is loaded */
266
  "pageLoaded": (pageno: number) => void;
267
  /** Fired when page changes */
268
  "pageChanged": (pageno: number) => void;
269
}
270
```
271

272
**Usage Examples:**
273

274
```javascript
275
// Page change event handling
276
table.on("pageChanged", function(pageno) {
277
  console.log(`Navigated to page ${pageno}`);
278
  
279
  // Update URL with current page
280
  const url = new URL(window.location);
281
  url.searchParams.set("page", pageno);
282
  window.history.replaceState({}, "", url);
283
  
284
  // Update page info display
285
  document.getElementById("current-page").textContent = pageno;
286
  document.getElementById("total-pages").textContent = table.getPageMax();
287
});
288

289
table.on("pageLoaded", function(pageno) {
290
  console.log(`Page ${pageno} data loaded`);
291
  
292
  // Scroll to top after page load
293
  table.getElement().scrollIntoView();
294
  
295
  // Update analytics
296
  if (window.gtag) {
297
    gtag("event", "page_view", {
298
      custom_map: { table_page: pageno }
299
    });
300
  }
301
});
302
```
303

304
## Custom Pagination Controls
305

306
### Building Custom Controls
307

308
Create custom pagination interfaces with full control over appearance and behavior.
309

310
```javascript { .api }
311
// Custom pagination control example
312
class CustomPaginationControls {
313
  constructor(table) {
314
    this.table = table;
315
    this.container = document.getElementById("custom-pagination");
316
    this.createControls();
317
    this.bindEvents();
318
  }
319
  
320
  createControls() {
321
    this.container.innerHTML = `
322
      <div class="pagination-controls">
323
        <button id="first-page" class="btn">First</button>
324
        <button id="prev-page" class="btn">Previous</button>
325
        <span class="page-info">
326
          Page <input id="page-input" type="number" min="1" style="width: 60px;"> 
327
          of <span id="total-pages">0</span>
328
        </span>
329
        <button id="next-page" class="btn">Next</button>
330
        <button id="last-page" class="btn">Last</button>
331
        <select id="page-size-select">
332
          <option value="10">10 per page</option>
333
          <option value="25">25 per page</option>
334
          <option value="50">50 per page</option>
335
          <option value="100">100 per page</option>
336
        </select>
337
      </div>
338
      <div class="pagination-info">
339
        Showing <span id="start-record">0</span> to <span id="end-record">0</span> 
340
        of <span id="total-records">0</span> records
341
      </div>
342
    `;
343
  }
344
  
345
  bindEvents() {
346
    const firstBtn = document.getElementById("first-page");
347
    const prevBtn = document.getElementById("prev-page");
348
    const nextBtn = document.getElementById("next-page");
349
    const lastBtn = document.getElementById("last-page");
350
    const pageInput = document.getElementById("page-input");
351
    const pageSizeSelect = document.getElementById("page-size-select");
352
    
353
    firstBtn.addEventListener("click", () => this.table.setPage(1));
354
    prevBtn.addEventListener("click", () => this.table.previousPage());
355
    nextBtn.addEventListener("click", () => this.table.nextPage());
356
    lastBtn.addEventListener("click", () => this.table.setPage(this.table.getPageMax()));
357
    
358
    pageInput.addEventListener("change", (e) => {
359
      const page = parseInt(e.target.value);
360
      if (page >= 1 && page <= this.table.getPageMax()) {
361
        this.table.setPage(page);
362
      }
363
    });
364
    
365
    pageSizeSelect.addEventListener("change", (e) => {
366
      this.table.setPageSize(parseInt(e.target.value));
367
    });
368
    
369
    // Update controls when page changes
370
    this.table.on("pageChanged", () => this.updateControls());
371
    this.table.on("dataLoaded", () => this.updateControls());
372
  }
373
  
374
  updateControls() {
375
    const currentPage = this.table.getPage();
376
    const maxPage = this.table.getPageMax();
377
    const pageSize = this.table.getPageSize();
378
    const totalRecords = this.table.getDataCount();
379
    
380
    document.getElementById("page-input").value = currentPage;
381
    document.getElementById("total-pages").textContent = maxPage;
382
    document.getElementById("page-size-select").value = pageSize;
383
    
384
    const startRecord = ((currentPage - 1) * pageSize) + 1;
385
    const endRecord = Math.min(currentPage * pageSize, totalRecords);
386
    
387
    document.getElementById("start-record").textContent = startRecord;
388
    document.getElementById("end-record").textContent = endRecord;
389
    document.getElementById("total-records").textContent = totalRecords;
390
    
391
    // Enable/disable navigation buttons
392
    document.getElementById("first-page").disabled = currentPage === 1;
393
    document.getElementById("prev-page").disabled = currentPage === 1;
394
    document.getElementById("next-page").disabled = currentPage === maxPage;
395
    document.getElementById("last-page").disabled = currentPage === maxPage;
396
  }
397
}
398

399
// Initialize custom controls
400
const customControls = new CustomPaginationControls(table);
401
```
402

403
## Performance Considerations
404

405
### Optimizing Large Datasets
406

407
```javascript { .api }
408
// Performance-optimized pagination setup
409
const optimizedTable = new Tabulator("#optimized-table", {
410
  data: veryLargeDataset,
411
  columns: columnDefinitions,
412
  
413
  // Essential for large datasets
414
  pagination: true,
415
  paginationMode: "local",
416
  paginationSize: 100,
417
  
418
  // Virtual DOM for rendering performance
419
  virtualDom: true,
420
  virtualDomBuffer: 200,
421
  
422
  // Reduce DOM manipulation
423
  layoutColumnsOnNewData: false,
424
  responsiveLayout: false,
425
  
426
  // Efficient data processing
427
  dataFiltered: function(filters, rows) {
428
    // Only process visible page data
429
    console.log(`Filtered to ${rows.length} rows`);
430
  }
431
});
432

433
// Memory management for very large datasets
434
function cleanupPagination() {
435
  // Clear unused page data from memory
436
  if (table.getDataCount() > 10000) {
437
    // Force garbage collection of filtered data
438
    table.redraw(true);
439
  }
440
}
441

442
// Clean up periodically
443
setInterval(cleanupPagination, 300000); // Every 5 minutes
444
```