munza-mui-data-grid

A feature-rich, headless-powered data grid for React — built on TanStack Table v8 and MUI. Sorting, filtering, pagination, row selection, column/row pinning, resizing, drag-and-drop column ordering, expandable rows, and split (frozen) columns — all out of the box.

Live Demo: https://munza-mui-data-grid.jsdevs.xyz/

Features

• Global search + per-column filtering (text, range)
• Multi-column sorting
• Client-side & manual (server-side) pagination
• Row selection with checkboxes
• Column pinning (left / right) and row pinning (top / bottom)
• Resizable & drag-to-reorder columns (@dnd-kit)
• Split view for frozen left/right columns
• Expandable rows with custom sub-components
• Persists per-grid layout (column order, sizing, visibility, pinning) via a storage key
• Built-in loading, error, and empty states
• Fully styled with MUI — themeable out of the box
• Bring your own toolbar actions via topRightSlot

Installation

npm install munza-mui-data-grid

Peer Dependencies

Make sure the following are installed in your project:

npm install react react-dom @mui/material @emotion/react @emotion/styled @mui/icons-material

Quick Start

import { Grid, useGridState, type ColumnDef } from 'munza-mui-data-grid';

interface User {
  id: string;
  name: string;
  email: string;
}

const columns: ColumnDef<User>[] = [
  { id: 'id', accessorKey: 'id', header: () => 'ID' },
  { id: 'name', accessorKey: 'name', header: () => 'Name' },
  { id: 'email', accessorKey: 'email', header: () => 'Email' },
];

const App = () => {
  const { state, handlers } = useGridState();

  return (
    <Grid
      payload={{ data: users, total: users.length }}
      columns={columns}
      state={state}
      {...handlers}
    />
  );
};

Server-Side (Manual) Pagination, Sorting & Filtering

const { state, handlers, rowSelection } = useGridState();

const { data, isLoading, isError, refetch, isFetching } = useUsersQuery({
  queryString: URLSearch(state),
});

<Grid
  payload={{ data: data?.rows ?? [], total: data?.total ?? 0 }}
  columns={columns}
  manualPagination
  isLoading={isLoading}
  isError={isError}
  isFetching={isFetching}
  refetch={refetch}
  state={state}
  {...handlers}
  height="55vh"
/>;

Toolbar Actions

Add custom action buttons to the toolbar via topRightSlot:

import AddIcon from '@mui/icons-material/Add';
import RefreshIcon from '@mui/icons-material/Refresh';
import IconButton from '@mui/material/IconButton';
import Stack from '@mui/material/Stack';
import Tooltip from '@mui/material/Tooltip';

<Grid
  columns={columns}
  payload={{ data, total }}
  state={state}
  {...handlers}
  topRightSlot={
    <Stack direction="row" spacing={1}>
      <Tooltip title="Refresh">
        <IconButton size="small" onClick={refetch}>
          <RefreshIcon fontSize="small" />
        </IconButton>
      </Tooltip>
      <Tooltip title="Add">
        <IconButton size="small" color="primary" onClick={handleAdd}>
          <AddIcon fontSize="small" />
        </IconButton>
      </Tooltip>
    </Stack>
  }
/>;

Working with Row Selection

Use the pluckSelected utility to extract a field from all selected rows:

import { pluckSelected } from 'munza-mui-data-grid';

const { rowSelection } = useGridState();

const selectedIds = pluckSelected(data, rowSelection, 'id');
// => ["V001", "V003", "V004"]

API Reference

<Grid /> Props

Prop	Type	Default	Description
payload	{ data: T[]; total: number }	—	Row data and total row count
columns	ColumnDef<T>[]	—	Column definitions (required)
state	Partial<TableState>	—	Controlled table state (from useGridState)
onColumnFiltersChange	OnChangeFn<ColumnFiltersState>	—	Column filter change handler
onPaginationChange	OnChangeFn<PaginationState>	—	Pagination change handler
onSortingChange	OnChangeFn<SortingState>	—	Sorting change handler
onRowSelectionChange	OnChangeFn<RowSelectionState>	—	Row selection change handler
setGlobalFilter	Dispatch<SetStateAction<string>>	—	Global search setter
manualPagination	boolean	false	Enables server-side pagination
isLoading	boolean	—	Shows skeleton loading rows
isError	boolean	—	Shows the error state
isFetching	boolean	—	Shows a background refetch indicator
refetch	() => void	—	Retry/refresh callback
renderSubComponent	(props: { row: Row<T> }) => ReactElement	—	Custom content for expanded rows
getRowCanExpand	(row: Row<T>) => boolean	—	Controls whether a row can expand
enableRowSelection	boolean	true	Enables/disables row selection
height	string	'65vh'	Fixed height of the scrollable table body
isToolbar	boolean	true	Shows/hides the built-in toolbar
isPagination	boolean	true	Shows/hides the built-in pagination controls
name	string	'munza'	Storage key for persisting per-grid layout
topRightSlot	React.ReactNode	—	Custom content on the right of the toolbar (e.g. action buttons)
children	React.ReactNode	—	Extra content rendered above the table (e.g. bulk-action bars)

useGridState()

Manages all controlled state required by <Grid />.

const { state, handlers, rowSelection } = useGridState();

Returns:

• state — { columnFilters, globalFilter, pagination, sorting, rowSelection }
• handlers — { onColumnFiltersChange, onPaginationChange, onSortingChange, setGlobalFilter, onRowSelectionChange }
• rowSelection — the current selection map, exposed directly for convenience

pluckSelected(data, rowSelection, field)

Extracts a field's value from every currently selected row.

pluckSelected(data, rowSelection, 'id'); // => string[]

URLSearch(queryArgs)

Serializes TanStack Table state into a MongoDB/Express-style query string.

URLSearch({
  pagination: { pageIndex: 0, pageSize: 20 },
  columnFilters: [{ id: 'status', value: 'active' }],
  sorting: [{ id: 'year', desc: true }],
  globalFilter: 'toyota',
});
// => "?page=1&limit=20&status=active&sort=-year&q=toyota"

Peer Dependency Versions

Package	Version
react / react-dom	^19.x
@mui/material	^9.x
@mui/icons-material	^9.x
@emotion/react / styled	^11.x

License

MIT