A component for managing grouped column headers in React Table Grid with support for custom rendering and styling

Table Header Group 📊

The TableHeaderGroup component manages grouped headers in your table, allowing you to organize related columns together in a clean and intuitive way. It automatically generates header groups based on column configurations and supports custom rendering.

Features ✨

🔄 Automatic group generation
📌 Support for pinned columns
🎨 Custom group rendering
🎭 With/without Tailwind styling
♿ Full accessibility support
📱 Responsive grid layout

Basic Usage

import { TableHeaderGroup } from '@shakibdshy/react-tablegrid';
 
function MyHeaderGroup() {
  const tableInstance = useTableGrid({
    columns: [
      {
        id: 'name',
        header: 'Name',
        group: 'personal',
      },
      {
        id: 'email',
        header: 'Email',
        group: 'personal',
      },
      {
        id: 'role',
        header: 'Role',
        group: 'account',
      },
    ],
    data,
  });
 
  return (
    <TableHeaderGroup
      tableInstance={tableInstance}
      className="my-header-groups"
    />
  );
}

Props

Required Props

`tableInstance`

The table instance from useTableGrid hook that manages the table state.

const tableInstance = useTableGrid<YourDataType>({
  columns,
  data,
});
 
<TableHeaderGroup tableInstance={tableInstance} />

Optional Props

`className`

Add custom CSS classes to the header group container.

<TableHeaderGroup
  className="custom-header-group"
  tableInstance={tableInstance}
/>

`style`

Add custom inline styles to the header group container.

<TableHeaderGroup
  style={{ backgroundColor: '#f9fafb' }}
  tableInstance={tableInstance}
/>

`TableColumnClassName`

Add custom CSS classes to each group header cell.

<TableHeaderGroup
  TableColumnClassName="custom-group-cell"
  tableInstance={tableInstance}
/>

`headerGroupClassName`

Add custom CSS classes specifically to the group headers.

<TableHeaderGroup
  headerGroupClassName="custom-group-header"
  tableInstance={tableInstance}
/>

`withoutTailwind`

Use without Tailwind CSS styling.

Type: boolean
Default: false

<TableHeaderGroup
  withoutTailwind={true}
  tableInstance={tableInstance}
/>

`customRender`

Custom render function for group headers.

<TableHeaderGroup
  customRender={{
    group: (group) => (
      <div className="flex items-center gap-2">
        <GroupIcon />
        <span>{group.name}</span>
        <span className="text-sm">({group.columns.length})</span>
      </div>
    ),
  }}
  tableInstance={tableInstance}
/>

Column Configuration

To create header groups, add a group property to your columns:

const columns = [
  {
    id: 'firstName',
    header: 'First Name',
    group: 'personal', // This column belongs to the 'personal' group
  },
  {
    id: 'lastName',
    header: 'Last Name',
    group: 'personal',
  },
  {
    id: 'email',
    header: 'Email',
    group: 'contact',
  },
];

Styling

With Tailwind (Default)

<TableHeaderGroup
  className="grid"
  TableColumnClassName="text-center font-bold"
  headerGroupClassName="bg-gray-50"
  tableInstance={tableInstance}
/>

Without Tailwind

<TableHeaderGroup
  withoutTailwind={true}
  className="rtg-header-group"
  TableColumnClassName="rtg-header-group-cell"
  tableInstance={tableInstance}
/>

Examples

Basic Header Groups

function BasicHeaderGroups() {
  const tableInstance = useTableGrid({
    columns: [
      {
        id: 'firstName',
        header: 'First Name',
        group: 'personal',
      },
      {
        id: 'lastName',
        header: 'Last Name',
        group: 'personal',
      },
      {
        id: 'email',
        header: 'Email',
        group: 'contact',
      },
      {
        id: 'phone',
        header: 'Phone',
        group: 'contact',
      },
    ],
    data,
  });
 
  return (
    <TableHeaderGroup
      tableInstance={tableInstance}
      className="border-b"
    />
  );
}

Custom Group Rendering

function CustomGroupHeaders() {
  const tableInstance = useTableGrid({
    columns: columns,
    data,
  });
 
  return (
    <TableHeaderGroup
      tableInstance={tableInstance}
      customRender={{
        group: (group) => (
          <div className="flex flex-col items-center p-2">
            <span className="font-bold">{group.name}</span>
            <span className="text-sm text-gray-500">
              {group.columns.length} columns
            </span>
          </div>
        ),
      }}
    />
  );
}

With Pinned Columns

function PinnedHeaderGroups() {
  const tableInstance = useTableGrid({
    columns: columns,
    data,
    pinnedColumns: {
      left: ['firstName', 'lastName'],
      right: ['actions'],
    },
  });
 
  return (
    <TableHeaderGroup
      tableInstance={tableInstance}
      className="relative"
    />
  );
}

Accessibility ♿

The TableHeaderGroup component implements these accessibility features:

role="rowgroup" for the container
role="columnheader" for group headers
aria-label for group descriptions
aria-colspan for proper group spans
Proper heading hierarchy
Screen reader support

Best Practices 💡

Use meaningful group names
Keep groups logically organized
Provide clear visual hierarchy
Consider responsive layouts
Maintain consistent styling
Use appropriate ARIA labels
Test with screen readers

Integration with TableGrid

The TableHeaderGroup is typically used within the TableGrid component:

function MyTable() {
  const tableInstance = useTableGrid({
    columns: groupedColumns,
    data,
  });
 
  return (
    <TableGrid
      tableInstance={tableInstance}
      // The TableHeaderGroup will be automatically rendered
      // when columns have group properties
    />
  );
}

Table Header Group 📊

On this page