Master-Detail Plugin

The Master-Detail plugin lets you create expandable detail rows that reveal additional content beneath each master row. Perfect for order/line-item UIs, employee/department views, or any scenario where you need to show related data without navigating away.

Installation

import '@toolbox-web/grid/features/master-detail';

Basic Usage

The key configuration is detailRenderer - a function that receives the row data and returns either an HTML string or a DOM element. This gives you complete control over what appears in the expanded detail area.

TypeScript

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

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'orderId', header: 'Order ID' },
    { field: 'customer', header: 'Customer' },
    { field: 'total', header: 'Total', type: 'currency' }
  ],
  features: {
    masterDetail: {
      detailRenderer: (row) => `
        <div class="order-details">
          <h4>Order Items</h4>
          <ul>
            ${row.items.map(item => `<li>${item.name} - $${item.price}</li>`).join('')}
          </ul>
        </div>
      `,
    },
  },
};

React

import '@toolbox-web/grid-react/features/master-detail';
import { DataGrid, GridDetailPanel } from '@toolbox-web/grid-react';

function OrderGrid({ orders }) {
  return (
    <DataGrid
      rows={orders}
      columns={[
        { field: 'orderId', header: 'Order ID' },
        { field: 'customer', header: 'Customer' },
        { field: 'total', header: 'Total', type: 'currency' }
      ]}
    >
      <GridDetailPanel>
        {({ row }) => (
          <div className="order-details">
            <h4>Order Items</h4>
            <ul>
              {row.items.map(item => (
                <li key={item.id}>{item.name} - ${item.price}</li>
              ))}
            </ul>
          </div>
        )}
      </GridDetailPanel>
    </DataGrid>
  );
}

Vue

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

const orders = [
  { orderId: 'ORD-001', customer: 'Alice', total: 150, items: [{ id: 1, name: 'Widget', price: 50 }, { id: 2, name: 'Gadget', price: 100 }] },
  { orderId: 'ORD-002', customer: 'Bob', total: 75, items: [{ id: 3, name: 'Tool', price: 75 }] },
];
</script>

<template>
  <TbwGrid :rows="orders" master-detail>
    <TbwGridColumn field="orderId" header="Order ID" />
    <TbwGridColumn field="customer" header="Customer" />
    <TbwGridColumn field="total" header="Total" type="currency" />

    <TbwGridDetailPanel v-slot="{ row }">
      <div class="order-details">
        <h4>Order Items</h4>
        <ul>
          <li v-for="item in row.items" :key="item.id">
            {{ item.name }} - ${{ item.price }}
          </li>
        </ul>
      </div>
    </TbwGridDetailPanel>
  </TbwGrid>
</template>

Angular

// Feature imports - GridMasterDetailDirective owns the [masterDetail] input,
// GridDetailView is the structural directive used inside <tbw-grid> for templating.
import {
  GridMasterDetailDirective,
  GridDetailView,
} from '@toolbox-web/grid-angular/features/master-detail';

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

@Component({
  selector: 'app-order-grid',
  imports: [Grid, GridMasterDetailDirective, GridDetailView],
  template: `
    <tbw-grid
      [rows]="orders"
      [columns]="columns"
      [masterDetail]="true"
      style="height: 400px; display: block;">
      <ng-template tbwDetailView let-row let-toggle="toggle">
        <div class="order-details">
          <h4>Order Items</h4>
          <ul>
            <li *ngFor="let item of row.items">
              {{ item.name }} - \${{ item.price }}
            </li>
          </ul>
          <button (click)="toggle()">Close</button>
        </div>
      </ng-template>
    </tbw-grid>
  `,
})
export class OrderGridComponent {
  orders = [/* order data */];

  columns: ColumnConfig[] = [
    { field: 'orderId', header: 'Order ID' },
    { field: 'customer', header: 'Customer' },
    { field: 'total', header: 'Total', type: 'currency' }
  ];
}

Use the GridDetailView directive (<ng-template tbwDetailView>) for Angular-idiomatic detail panels with template context (let-row, let-toggle="toggle"). For non-Angular consumers of the same plugin, an inline detailRenderer: (row) => HTMLElement | string is also accepted in gridConfig.masterDetail.

Demos

Default Master-Detail

DETAIL

Animation Expand/collapse animation

slideexpandfadenone

Expand on row click Toggle detail panel by clicking row

Detail height Height of detail panel (px or auto)

auto100150200250

Show source

Configuration Options

See MasterDetailConfig for the full list of options and their defaults.

Animation Options

The animation option controls how detail rows appear/disappear:

// Slide animation (default)
features: { masterDetail: { animation: 'slide', ... } }

// Fade animation
features: { masterDetail: { animation: 'fade', ... } }

// No animation
features: { masterDetail: { animation: false, ... } }

Note

Animation respects the grid-level animation.mode setting. If the grid has animation: { mode: 'off' }, plugin animations are disabled.

Server-Side Data

Requires: ServerSidePlugin — see Server-Side Plugin

When ServerSidePlugin is loaded, master rows are lazily loaded via virtual scrolling (infinite scroll) or pagination — the same way flat data, Tree, or Row Grouping work. MasterDetail does not claim root data, so master rows flow through ServerSide’s block cache unchanged.

Detail data can be fetched on demand or embedded in the master row:

• Async detail data: On detail expand, MasterDetailPlugin queries datasource:fetch-children. ServerSide calls getChildRows() and delivers the result.
• Embedded detail data: If detail data is already in the master row object (e.g. row.items), detailRenderer accesses it directly — no getChildRows() needed.

When ServerSide is not present, detailRenderer works synchronously from the row object.

import '@toolbox-web/grid/features/master-detail';
import '@toolbox-web/grid/features/server-side';
import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'orderId', header: 'Order ID' },
    { field: 'customer', header: 'Customer' },
    { field: 'total', header: 'Total', type: 'currency' },
  ],
  features: {
    serverSide: {
      pageSize: 50,
      dataSource: {
        async getRows(params) {
          const res = await fetch(`/api/orders?start=${params.startNode}&end=${params.endNode}`);
          const data = await res.json();
          return { rows: data.orders, totalNodeCount: data.total };
        },
        async getChildRows(params) {
          const { row } = params.context;
          const res = await fetch(`/api/orders/${row.id}/items`);
          return { rows: await res.json() };
        },
      },
    },
    masterDetail: {
      detailRenderer: (row, rowIndex) => {
        const plugin = grid.getPluginByName('masterDetail');

        if (plugin.isDetailLoading(rowIndex)) {
          return '<div class="loading">Loading order items…</div>';
        }

        const items = plugin.getDetailData(rowIndex);
        if (!items) {
          return '<div class="loading">Loading…</div>';
        }

        return `
          <div class="order-details">
            <h4>Order Items</h4>
            <ul>
              ${items.map((item: any) => `<li>${item.name} — $${item.price}</li>`).join('')}
            </ul>
          </div>
        `;
      },
    },
  },
};

Data flow:

1. ServerSide fetches master rows in blocks (virtual scroll or pagination) → renders normally (MasterDetail does not claim root data)
2. User scrolls → ServerSide loads more master rows on demand
3. On detail expand → MasterDetailPlugin queries datasource:fetch-children with { source: 'master-detail', row, rowIndex }
4. ServerSide calls getChildRows() → broadcasts datasource:children
5. MasterDetailPlugin stores the data and re-renders the detail panel
6. detailRenderer uses getDetailData(rowIndex) to access the async data

Async API:

const plugin = grid.getPluginByName('masterDetail');
plugin.getDetailData(rowIndex);     // Get fetched detail data (or undefined if not loaded)
plugin.isDetailLoading(rowIndex);   // Check if detail data is currently loading

Note

Child rows are fetched as a single batch — no pagination. If a detail row has many children, limit the response server-side.

Nested Grid Example

features: {
  masterDetail: {
    detailRenderer: (row) => {
      const childGrid = document.createElement('tbw-grid');
      childGrid.style.height = '200px';
      childGrid.gridConfig = { columns: [...] };
      childGrid.rows = row.items || [];
      return childGrid;
    },
  },
},

Programmatic API

See MasterDetailPlugin for the full list of methods.

const plugin = grid.getPluginByName('masterDetail');

plugin.expand(rowIndex);
plugin.collapse(rowIndex);
plugin.toggle(rowIndex);
plugin.expandAll();
plugin.collapseAll();
plugin.isExpanded(rowIndex); // boolean

Styling

The master-detail plugin supports CSS custom properties for theming. Override these on tbw-grid or a parent container:

CSS Custom Properties

Property	Default	Description
--tbw-master-detail-bg	var(--tbw-color-row-alt)	Detail row background
--tbw-master-detail-border	var(--tbw-color-border)	Detail row border
--tbw-detail-padding	1em	Detail content padding
--tbw-detail-max-height	31.25rem (~500px)	Max height for animation
--tbw-animation-duration	200ms	Expand/collapse animation
--tbw-animation-easing	ease-out	Animation curve

Example

tbw-grid {
  /* Custom master-detail styling */
  --tbw-master-detail-bg: #f8f9fa;
  --tbw-master-detail-border: #dee2e6;
  --tbw-detail-padding: 1.5rem;
  --tbw-animation-duration: 300ms;
}

CSS Classes

The master-detail plugin uses these class names:

Class	Element
.master-detail-expander	Expander cell container
.master-detail-toggle	Expand/collapse icon
.master-detail-row	Detail row container
.master-detail-row.tbw-expanding	Row during expand animation
.master-detail-row.tbw-collapsing	Row during collapse animation
.master-detail-cell	Detail content wrapper

Events

Click the expand arrow to open/close row details.

Event Log: Clear

Event	Detail	Description
detail-expand	{ rowIndex, row, expanded }	Fired when a detail row is expanded/collapsed

See Also

• Tree — Hierarchical tree data
• Row Grouping — Group rows by field values; master-detail toggles appear on data rows within groups
• Selection — Row and cell selection