ResponsivePlugin

Responsive Plugin for tbw-grid

Adds automatic card layout mode when the grid width falls below a configurable breakpoint. Perfect for responsive designs, split-pane UIs, and mobile viewports.

Examples

// Basic usage - switch to card layout below 500px
const config: GridConfig = {
  plugins: [new ResponsivePlugin({ breakpoint: 500 })],
};

// Hide less important columns in card mode
const config: GridConfig = {
  plugins: [
    new ResponsivePlugin({
      breakpoint: 600,
      hiddenColumns: ['createdAt', 'updatedAt'],
    }),
  ],
};

// Custom card renderer for advanced layouts
const config: GridConfig = {
  plugins: [
    new ResponsivePlugin({
      breakpoint: 400,
      cardRenderer: (row) => {
        const card = document.createElement('div');
        card.className = 'custom-card';
        card.innerHTML = `<strong>${row.name}</strong><br>${row.email}`;
        return card;
      },
    }),
  ],
};

Extends BaseGridPlugin

Inherited methods like attach(), detach(), afterRender(), etc. are documented in the base class.

Properties

Property	Type	Description
name	responsive	Unique plugin identifier (derived from class name by default)
version	1.0.0	Plugin version - defaults to grid version for built-in plugins. Third-party plugins can override with their own semver.
styles	string	CSS styles to inject into the grid’s shadow DOM
manifest	PluginManifest	Plugin manifest declaring incompatibilities with other plugins.

Methods

isResponsive()

Check if currently in responsive mode.

isResponsive(): boolean

Returns

boolean - true if the grid is in card layout mode

---

setResponsive()

Force responsive mode regardless of width. Useful for testing or manual control.

setResponsive(enabled: boolean): void

Parameters

Name	Type	Description
enabled	boolean	Whether to enable responsive mode

---

setBreakpoint()

Update breakpoint dynamically.

setBreakpoint(width: number): void

Parameters

Name	Type	Description
width	number	New breakpoint width in pixels

---

setCardRenderer()

Set a custom card renderer. This allows framework adapters to provide template-based renderers at runtime.

setCardRenderer(renderer: (row: T, rowIndex: number, column: ColumnConfig<any>) => HTMLElement | undefined): void

Parameters

Name	Type	Description
renderer	(row: T, rowIndex: number, column: ColumnConfig<any>) => HTMLElement | undefined	The card renderer function, or undefined to use default

---

getWidth()

Get current grid width.

getWidth(): number

Returns

number - Width of the grid element in pixels

---

getActiveBreakpoint()

Get the currently active breakpoint config (multi-breakpoint mode only).

getActiveBreakpoint(): BreakpointConfig | null

Returns

BreakpointConfig | null - The active BreakpointConfig, or null if no breakpoint is active

---

attach()

override — Called when the plugin is attached to a grid. Override to set up event listeners, initialize state, etc.

attach(grid: GridElement): void

Parameters

Name	Type	Description
grid	GridElement

Example

attach(grid: GridElement): void {
  super.attach(grid);
  // Set up document-level listeners with auto-cleanup
  document.addEventListener('keydown', this.handleEscape, {
    signal: this.disconnectSignal
  });
}

---

detach()

override — Called when the plugin is detached from a grid. Override to clean up event listeners, timers, etc.

detach(): void

Example

detach(): void {
  // Clean up any state not handled by disconnectSignal
  this.selectedRows.clear();
  this.cache = null;
}

---

afterRender()

override — Apply hidden and value-only columns. In legacy mode (single breakpoint), only applies when in responsive mode. In multi-breakpoint mode, applies whenever there’s an active breakpoint.

afterRender(): void

---

renderRow()

override — Custom row rendering when cardRenderer is provided and in responsive mode.

When a cardRenderer is configured, this hook takes over row rendering to display the custom card layout instead of the default cell structure.

renderRow(row: unknown, rowEl: HTMLElement, rowIndex: number): boolean | void

Parameters

Name	Type	Description
row	unknown	The row data object
rowEl	HTMLElement	The row DOM element to render into
rowIndex	number	The index of the row in the data array

Returns

boolean | void - true if rendered (prevents default), void for default rendering

---

onKeyDown()

override — Handle keyboard navigation in responsive mode.

In responsive mode, the visual layout is inverted:

• Cells are stacked vertically within each “card” (row)
• DOWN/UP visually moves within the card (between fields)
• Page Down/Page Up or Ctrl+Down/Up moves between cards

For custom cardRenderers, keyboard navigation is disabled entirely since the implementor controls the card content and should handle navigation via their own event handlers.

onKeyDown(e: KeyboardEvent): boolean

Parameters

Name	Type	Description
e	KeyboardEvent

Returns

boolean - true if the event was handled and default behavior should be prevented

---

getExtraHeight()

⚠️ Deprecated: Use getRowHeight() instead. This hook will be removed in v2.0.

override — Return total extra height contributed by mixed row heights. This is called by the grid’s virtualization system to adjust scrollbar height.

The grid calculates: totalRows * baseRowHeight + pluginExtraHeight

For mixed layouts (groups + cards), we need to report the difference between actual heights and what the base calculation assumes:

• Extra for groups: groupCount * (groupHeight - baseHeight)
• Extra for cards: cardCount * (cardHeight - baseHeight)

getExtraHeight(): number

---

getExtraHeightBefore()

⚠️ Deprecated: Use getRowHeight() instead. This hook will be removed in v2.0.

override — Return extra height that appears before a given row index. Used by virtualization to correctly calculate scroll positions.

Like getExtraHeight, this accounts for both group and card row heights.

getExtraHeightBefore(beforeRowIndex: number): number

Parameters

Name	Type	Description
beforeRowIndex	number

---

getRowHeight()

override — Get the height of a specific row based on its type (group row vs card row). Returns undefined if not in responsive mode.

getRowHeight(row: unknown, _index: number): number | undefined

Parameters

Name	Type	Description
row	unknown	The row data
_index	number	The row index (unused, but part of the interface)

Returns

number | undefined - The row height in pixels, or undefined if not in responsive mode

---