# 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](/grid/plugins/responsive/interfaces/responsivepluginconfig.md)

| Option | Type | Description |
| ------ | ---- | ----------- |
| `breakpoint?` | <code>number</code> | Width threshold in pixels to trigger responsive mode. When grid width &lt; breakpoint, switches to card layout. |
| `breakpoints?` | <code><a href="/grid/plugins/responsive/interfaces/breakpointconfig/">BreakpointConfig</a>[]</code> | Multiple breakpoints for progressive degradation. Evaluated from smallest to largest maxWidth. When provided, the single `breakpoint` property is ignored. |
| `cardRenderer?` | <code>(row: T, rowIndex: number, column: <a href="/grid/api/core/interfaces/columnconfig/">ColumnConfig</a>&lt;any&gt;) =&gt; HTMLElement</code> | Custom renderer function for card layout. If not provided, uses CSS-only default layout (header: value pairs). |
| `hideHeader?` | <code>boolean</code> | Whether to hide the per-field label rendered inside each card. |
| `cardRowHeight?` | <code>number &#124; auto</code> | Card row height in pixels. Only applies when cardRenderer is provided. Use 'auto' for dynamic height based on content. |
| `debounceMs?` | <code>number</code> | Debounce delay in ms for resize events. |
| `hiddenColumns?` | <code><a href="/grid/plugins/responsive/types/hiddencolumnconfig/">HiddenColumnConfig</a>[]</code> | 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. |
| `animate?` | <code>boolean</code> | Enable smooth animations when transitioning between modes. |
| `animationDuration?` | <code>number</code> | Animation duration in milliseconds. |

## Examples

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

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

```ts
// 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](/docs/grid-api-plugin-development-classes-basegridplugin--docs)
>
> Inherited methods like `attach()`, `detach()`, `afterRender()`, etc. are documented in the base class.

## Properties

| Property | Type | Description |
| -------- | ---- | ----------- |
| `name` | <code>responsive</code> | Unique plugin identifier (derived from class name by default) |
| `version` | <code>1.0.0</code> | Plugin version - defaults to grid version for built-in plugins. Third-party plugins can override with their own semver. |
| `styles` | <code>string</code> | CSS styles to inject via `document.adoptedStyleSheets` |
| `manifest` | <code><a href="/grid/api/plugin-development/interfaces/pluginmanifest/">PluginManifest</a></code> | Plugin manifest declaring queries this plugin handles. |

## Methods

### isResponsive()

Check if currently in responsive mode.

```ts
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.

```ts
setResponsive(enabled: boolean): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `enabled` | <code>boolean</code> | Whether to enable responsive mode |

***

### setBreakpoint()

Update breakpoint dynamically.

```ts
setBreakpoint(width: number): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `width` | <code>number</code> | New breakpoint width in pixels |

***

### setCardRenderer()

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

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

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `renderer` | <code>(row: T, rowIndex: number, column: <a href="/grid/api/core/interfaces/columnconfig/">ColumnConfig</a>&lt;any&gt;) =&gt; HTMLElement &#124; undefined</code> | The card renderer function, or undefined to use default |

***

### getWidth()

Get current grid width.

```ts
getWidth(): number
```

#### Returns

`number` - Width of the grid element in pixels

***

### getActiveBreakpoint()

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

```ts
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.

```ts
attach(grid: GridElement): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `grid` | <code>GridElement</code> |  |

#### Example

```ts
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.

```ts
detach(): void
```

#### Example

```ts
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.

```ts
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.

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

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `row` | <code>unknown</code> | The row data object |
| `rowEl` | <code>HTMLElement</code> | The row DOM element to render into |
| `rowIndex` | <code>number</code> | 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.

```ts
onKeyDown(e: KeyboardEvent): boolean
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `e` | <code>KeyboardEvent</code> |  |

#### 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.

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

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `row` | <code>unknown</code> | The row data |
| `_index` | <code>number</code> | The row index (unused, but part of the interface) |

#### Returns

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

***