ResponsivePlugin

Since v1.1.0

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.

Configuration Options

Option	Type	Description
breakpoint?	number	Width threshold in pixels to trigger responsive mode. When grid width < breakpoint, switches to card layout.
breakpoints?	BreakpointConfig[]	Multiple breakpoints for progressive degradation. Evaluated from smallest to largest maxWidth. When provided, the single breakpoint property is ignored.
cardRenderer?	(row: T, rowIndex: number, column: ColumnConfig<any, ColumnFieldKey<any>>) => HTMLElement	Custom renderer function for card layout. If not provided, uses CSS-only default layout (header: value pairs).
hideHeader?	boolean	Whether to hide the per-field label rendered inside each card.
cardRowHeight?	number | auto	Card row height in pixels. Only applies when cardRenderer is provided. Use ‘auto’ for dynamic height based on content.
debounceMs?	number	Minimum interval in ms between layout switches.
hiddenColumns?	HiddenColumnConfig[]	Columns to hide in responsive mode (when using CSS-only default). Useful for hiding less important columns in card view. Supports enhanced syntax with showValue option.
animation?	ResponsiveAnimation	How the switch between table and card layout is animated.
animate?	boolean	Enable smooth animations when transitioning between modes.
animationDuration?	number	Animation duration in milliseconds.

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 via document.adoptedStyleSheets
manifest	PluginManifest	Plugin manifest declaring queries this plugin handles.

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, ColumnFieldKey<any>>) => HTMLElement | undefined): void

Parameters

Name	Type	Description
renderer	(row: T, rowIndex: number, column: ColumnConfig<any, ColumnFieldKey<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

---

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

---