Playwright Smart Table

Appearance

Config Options ​

All options passed to useTable(locator, config). Every option is optional unless noted.

typescript
import { useTable } from '@rickcedwhat/playwright-smart-table';

const table = await useTable(page.locator('#my-table'), {
  rowSelector: 'tbody tr',
  maxPages: 20,
  strategies: { ... },
}).init();

→ API: Table Methods · API: Strategies

Selectors ​

headerSelector ​

Signature ​

typescript
headerSelector?: Selector

Selector for the column header elements. Accepts a CSS string or a function returning a Locator.

typescript
// CSS string
headerSelector: 'thead th'

// Locator function
headerSelector: (root) => root.locator('[role="columnheader"]')

→ Guide: Identify Your Table

rowSelector ​

Signature ​

typescript
rowSelector?: Selector

CSS selector for the table rows. Scoped to the table locator.

typescript
rowSelector: 'tbody tr'
rowSelector: '[role="row"].data-row'

→ Guide: Identify Your Table

cellSelector ​

Signature ​

typescript
cellSelector?: Selector

Selector for cells within a row. Accepts a CSS string or a function returning a Locator.

typescript
// CSS string
cellSelector: 'td'

// Locator function
cellSelector: (row) => row.locator('[role="gridcell"]')

→ Guide: Identify Your Table

Behavior ​

maxPages ​

Signature ​

typescript
maxPages?: number

Maximum number of pages to scan during iteration and search operations. Prevents runaway pagination on unexpectedly large tables.

typescript
maxPages: 50

concurrency ​

Signature ​

typescript
concurrency?: RowIterationMode

Default concurrency mode for forEach, map, and filter. Can be overridden per-call.

  • 'sequential' — one row at a time, in order. Default for forEach and filter.
  • 'parallel' — all rows on the current page run concurrently. Default for map.
  • 'synchronized' — rows run in parallel but page navigation waits for all callbacks to finish.
typescript
concurrency: 'sequential'

→ Guide: Iterate Rows

autoScroll ​

Signature ​

typescript
autoScroll?: boolean

When true, PST scrolls the table locator into view during init(). Useful when tables render below the fold.

typescript
autoScroll: true

Hooks ​

headerTransformer ​

Signature ​

typescript
headerTransformer?: (args: {
  text: string,
  index: number,
  locator: Locator
}) => string | Promise<string>

Rename or normalize column headers at init time. Runs once per header cell during init().

typescript
headerTransformer: ({ text, index }) => text.trim() || `Column ${index}`
typescript
// Rename a known system column
headerTransformer: ({ text }) =>
  text.includes('__checkbox__') ? 'Select' : text.trim()

→ Guide: Custom Header Text

onReset ​

Signature ​

typescript
onReset?: (context: TableContext) => Promise<void>

Called after table.reset(). Use to navigate back to the first page, clear filters, or perform any teardown the table requires.

typescript
onReset: async ({ root, page }) => {
  await page.locator('.pagination-first').click();
}

Advanced ​

columnOverrides ​

Signature ​

typescript
columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>

Per-column read and write overrides. Use read to customize how cell text is extracted; use write to customize how values are filled.

typescript
columnOverrides: {
  Status: {
    read: async (cell) => cell.locator('.badge').innerText(),
    write: async ({ cell, targetValue }) => {
      await cell.locator('select').selectOption(targetValue);
    },
  },
}

→ Guide: Column Overrides · Guide: Fill Cells

debug ​

Signature ​

typescript
debug?: boolean | DebugConfig

Enable verbose logging for development. Pass true for default verbosity or a config object for fine-grained control.

typescript
debug: true

debug: { logLevel: 'verbose' }

strategies ​

Signature ​

typescript
strategies?: Partial<TableStrategies>

All pluggable strategy overrides — pagination, loading detection, header discovery, sorting, viewport navigation, and more.

typescript
strategies: {
  pagination: PaginationStrategies.infiniteScroll({ ... }),
  loading: { isCellLoading: async (cell) => ... },
}

→ API: Strategies