Responsive Plugin

The Responsive plugin transforms the grid from a tabular layout to a card/list layout when the grid width falls below a configurable breakpoint. This enables grids to work seamlessly in narrow containers like split-pane UIs, mobile viewports, and dashboard widgets.

Installation

import '@toolbox-web/grid/features/responsive';

Basic Usage

Vanilla JS

import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/responsive';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
  ],
  features: {
    responsive: { breakpoint: 500 },
  },
};
grid.rows = data;

React

import '@toolbox-web/grid-react/features/responsive';
import { DataGrid } from '@toolbox-web/grid-react';

function MyGrid({ data }) {
  return (
    <DataGrid
      rows={data}
      columns={[
        { field: 'id', header: 'ID' },
        { field: 'name', header: 'Name' },
        { field: 'email', header: 'Email' },
      ]}
      responsive={{ breakpoint: 500 }}
      style={{ height: '400px' }}
    />
  );
}

Vue

<script setup>
import '@toolbox-web/grid-vue/features/responsive';
import { TbwGrid, TbwGridColumn } from '@toolbox-web/grid-vue';

const data = [
  { id: 1, name: 'Alice', email: 'alice@example.com' },
  { id: 2, name: 'Bob', email: 'bob@example.com' },
];
</script>

<template>
  <TbwGrid :rows="data" :responsive="{ breakpoint: 500 }" style="height: 400px">
    <TbwGridColumn field="id" header="ID" />
    <TbwGridColumn field="name" header="Name" />
    <TbwGridColumn field="email" header="Email" />
  </TbwGrid>
</template>

Angular

// Feature import - enables the [responsive] input
import '@toolbox-web/grid-angular/features/responsive';

import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-my-grid',
  imports: [Grid],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [responsive]="{ breakpoint: 500 }"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  rows = [
    { id: 1, name: 'Alice', email: 'alice@example.com' },
    { id: 2, name: 'Bob', email: 'bob@example.com' },
  ];

  columns: ColumnConfig[] = [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
  ];
}

Demos

Interactive Demo

RESPONSIVE

Breakpoint (px) Width threshold for card layout

500

Hide header Hide column headers in card layout

Animate Smooth transitions between modes

Hidden columns Columns to hide in card mode

email startDate salary

Debounce (ms) Resize debounce delay

100

↔ Drag the right edge to resize the container

Show source

Resize the container to see the grid switch between table and card layouts.

Manual Control

Show source

Use the plugin API to manually control responsive mode.

Custom Card Renderer

↔ Resize to see custom card layout

Show source

Use cardRenderer for complete control over card layout - avatars, badges, custom layouts, etc.

Fixed Card Height

Each card has a fixed 60px height

Show source

Use cardRowHeight for consistent card heights, which helps virtualization performance.

Progressive Degradation

↔ Resize to see columns hide progressively

Show source

Use multiple breakpoints to progressively hide columns before switching to card layout.

Value-Only Columns

Email shows without label, Start Date is fully hidden

Show source

Use enhanced hiddenColumns syntax to show values without labels.

Animated Transitions

↔ Resize below 500px to see animated transition

Show source

Smooth animations when transitioning between modes (enabled by default).

Light DOM Configuration

The ResponsivePlugin supports declarative configuration via the <tbw-grid-responsive-card> element. Framework adapters provide wrapper components with idiomatic rendering patterns.

Vanilla JS

<tbw-grid>
  <tbw-grid-responsive-card
    breakpoint="500"
    card-row-height="80"
    hidden-columns="createdAt, updatedAt"
    hide-header="true">
    <div class="custom-card">
      <strong>{{ row.name }}</strong>
      <span>{{ row.email }}</span>
    </div>
  </tbw-grid-responsive-card>
</tbw-grid>

In vanilla JS, the innerHTML of the element is used as a template. Use {{ row.fieldName }} syntax for value interpolation.

React

import { DataGrid, GridResponsiveCard } from '@toolbox-web/grid-react';

<DataGrid rows={data} columns={columns} responsive={{ breakpoint: 500 }}>
  <GridResponsiveCard<Employee> cardRowHeight={80}>
    {({ row, index }) => (
      <div className="custom-card">
        <strong>{row.name}</strong>
        <span>{row.email}</span>
      </div>
    )}
  </GridResponsiveCard>
</DataGrid>

React uses a render function as children, receiving { row, index }.

Vue

<script setup>
import { TbwGrid, TbwGridResponsiveCard } from '@toolbox-web/grid-vue';
</script>

<template>
  <TbwGrid :rows="data" :columns="columns" :responsive="{ breakpoint: 500 }">
    <TbwGridResponsiveCard>
      <template #default="{ row, rowIndex }">
        <div class="custom-card">
          <strong>{{ row.name }}</strong>
          <span>{{ row.email }}</span>
        </div>
      </template>
    </TbwGridResponsiveCard>
  </TbwGrid>
</template>

Vue uses a scoped slot, receiving { row, rowIndex }.

Angular

<tbw-grid [rows]="data" [columns]="columns" [responsive]="{ breakpoint: 500 }">
  <tbw-grid-responsive-card>
    <ng-template let-row let-index="index">
      <div class="custom-card">
        <strong>{{ row.name }}</strong>
        <span>{{ row.email }}</span>
      </div>
    </ng-template>
  </tbw-grid-responsive-card>
</tbw-grid>

Angular uses <ng-template> with implicit context binding (let-row, let-index="index"). Import GridResponsiveCard from @toolbox-web/grid-angular.

Vanilla Attributes

Attribute	Type	Description
breakpoint	number	Width threshold in pixels for responsive mode
card-row-height	number | 'auto'	Card height in pixels or auto
hidden-columns	string	Comma-separated field names to hide
hide-header	'true' | 'false'	Hide header row in responsive mode
debounce-ms	number	Resize debounce delay in ms

Note

Light DOM attributes override constructor config when both are present.

Configuration Options

See ResponsivePluginConfig for the full list of options and defaults.

BreakpointConfig

For progressive degradation, use the breakpoints array instead of a single breakpoint. See BreakpointConfig for the full interface.

HiddenColumnConfig

The enhanced hiddenColumns syntax supports both simple strings and objects. See HiddenColumnConfig for the full type definition.

Example:

hiddenColumns: [
  'startDate',                        // Fully hidden
  { field: 'email', showValue: true }, // Value shown without label
]

Choosing a Breakpoint

The breakpoint should be based on your grid’s column count and content:

Grid Size	Suggested Breakpoint
3-5 columns	400-500px
6-10 columns	600-800px
10+ columns	900-1200px

Note

If no breakpoint is configured (or set to 0), a warning is logged and responsive mode is effectively disabled.

Events

Resize the browser window below the breakpoint (600 px) to trigger card mode.

Event Log: Clear

responsive-change

Emitted when the grid crosses the breakpoint threshold:

grid.on('responsive-change', ({ isResponsive, width, breakpoint }) => {
  console.log(isResponsive ? 'Card mode' : 'Table mode');
  console.log(`Width: ${width}px, Breakpoint: ${breakpoint}px`);
});

Programmatic API

Control responsive mode programmatically via the plugin instance:

// Get the plugin instance from the grid
const plugin = grid.getPluginByName('responsive');

// Check current mode
const isCardMode = plugin.isResponsive();

// Force responsive mode (regardless of width)
plugin.setResponsive(true);
plugin.setResponsive(false);

// Update breakpoint dynamically
plugin.setBreakpoint(600);

// Get current grid width
const width = plugin.getWidth();

// Get active breakpoint (multi-breakpoint mode)
const activeBreakpoint = plugin.getActiveBreakpoint();
// Returns: { maxWidth: 600, hiddenColumns: [...], cardLayout: false } or null

How It Works

1. ResizeObserver monitors the grid element’s width
2. When width < breakpoint, the plugin adds data-responsive attribute to the grid
3. CSS transforms cells from horizontal to vertical layout
4. Each cell displays “Header: Value” using the ::before pseudo-element with data-header attribute

This CSS-only approach means:

• No DOM replacement or re-rendering needed
• Smooth transitions between modes
• Works with all other plugins (selection, editing, etc.)

Styling

The responsive plugin uses the grid’s existing CSS custom properties for theming.

CSS Custom Properties

The responsive plugin uses the grid’s built-in CSS variables:

Property	Description
--tbw-cell-padding	Padding inside card rows
--tbw-color-border	Card separator color
--tbw-color-bg	Card background color
--tbw-color-row-alt	Alternating card background
--tbw-color-row-hover	Card hover background
--tbw-color-selection	Selected card background
--tbw-color-header-fg	Label text color
--tbw-color-accent	Selection indicator color

Custom Card Styling

/* Custom card styling */
tbw-grid[data-responsive] .data-grid-row {
  border-radius: 8px;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
  margin-bottom: 8px;
}

/* Hide specific columns in card mode */
tbw-grid[data-responsive] .cell[data-field="createdAt"],
tbw-grid[data-responsive] .cell[data-field="updatedAt"] {
  display: none;
}

Data Attributes

Attribute	Element	Description
data-responsive	tbw-grid	Present when in responsive (card) mode
data-responsive-animate	tbw-grid	Present when animations are enabled
data-header	.cell	Column header text for CSS ::before
data-responsive-hidden	.cell	Marks cells hidden via hiddenColumns
data-responsive-value-only	.cell	Marks cells showing value only (no label)

CSS Custom Properties for Animation

Property	Default	Description
--tbw-responsive-duration	200ms	Animation duration for mode transitions

Keyboard Shortcuts

In responsive mode, the visual layout is inverted - cells are stacked vertically within each card. The plugin automatically adjusts keyboard navigation to match this layout:

Key	Table Mode	Responsive Mode
↑	Previous row	Previous field (within card), wraps to previous card
↓	Next row	Next field (within card), wraps to next card
←	Previous column	Previous card (same field)
→	Next column	Next card (same field)
Tab	Next cell, wraps to next row	Same behavior
Enter	Start editing	Same behavior
Escape	Cancel editing	Same behavior

Custom Card Renderers

When using cardRenderer (Phase 2), the grid’s built-in keyboard navigation is disabled for arrow keys. Implementors should handle navigation within their custom card content via their own event handlers.

Use Cases

Split-Pane UI

// Grid in a resizable panel
features: {
  responsive: {
    breakpoint: 400,
    hiddenColumns: ['createdAt', 'updatedAt'], // Hide dates in card mode
  },
},

Mobile-First Design

// Responsive grid for mobile/tablet
features: {
  responsive: {
    breakpoint: 768,
    hideHeader: true,
  },
},

Dashboard Widget

// Small widget in dashboard
features: {
  responsive: {
    breakpoint: 300,
    hiddenColumns: ['email', 'phone', 'address'],
  },
},

Progressive Degradation

// Gracefully degrade as container shrinks
features: {
  responsive: {
    breakpoints: [
      { maxWidth: 900, hiddenColumns: ['startDate'] },
      { maxWidth: 700, hiddenColumns: ['startDate', 'email'] },
      { maxWidth: 500, cardLayout: true },
    ],
  },
},

Custom Card Renderer

For advanced card layouts with avatars, badges, or custom grouped fields, use the cardRenderer option:

features: {
  responsive: {
    breakpoint: 600,
    cardRenderer: (row, rowIndex) => {
      const card = document.createElement('div');
      card.className = 'employee-card';
      card.innerHTML = `
        <div class="avatar">${row.name[0]}</div>
        <div class="info">
          <div class="name">${row.name}</div>
          <div class="meta">${row.department} · $${row.salary.toLocaleString()}</div>
          <div class="email">${row.email}</div>
        </div>
      `;
      return card;
    },
  },
},

cardRenderer Signature

cardRenderer: (row: T, rowIndex: number) => HTMLElement

Parameter	Type	Description
row	T	The row data object
rowIndex	number	Index of the row in the data array
Returns	HTMLElement	The element to render as the card content

cardRowHeight

When using cardRenderer, you can control card height:

// Fixed height (better for virtualization with large datasets)
features: {
  responsive: {
    breakpoint: 600,
    cardRowHeight: 80,  // 80px per card
    cardRenderer: (row) => { /* ... */ },
  },
},

// Auto height (default - cards size to content)
features: {
  responsive: {
    breakpoint: 600,
    cardRowHeight: 'auto',
    cardRenderer: (row) => { /* ... */ },
  },
},

Keyboard Navigation with cardRenderer

When using a custom cardRenderer, the grid’s built-in arrow key navigation is disabled. This allows you to implement your own navigation within the card content.

Standard keyboard shortcuts still work:

• Tab - Move between cards
• Enter - Triggers cell-activate event
• Escape - Standard escape handling

See Also

• Selection — Row and cell selection
• Theming — CSS custom properties for styling