Data Grid
<wa-data-grid>
Data grids display tabular data with sorting, selection, filtering, pinning, tree data, grouping with aggregation, column footers, expandable rows, pagination, CSV export, full keyboard navigation, and virtualization for large datasets.
-
Pro Components -
Responsive Layout Tools -
Ever-Growing Pattern Library -
Unlimited Hosted Projects -
Pre-Built Pro Themes -
Pro Theme Builder -
Pro Color Tools -
Official Figma Design Kit Newer additions to Web Awesome, like <wa-toast>, aren't included in the currently available kit, but a new version is in the works.
Track its progress on GitHub. -
WA Pro Perpetual License -
Actual Human™ Support
Already have Pro? Log in
Like the chart components, data grids are driven by JavaScript properties. Set data and columns on the element and the grid handles rendering, sorting, filtering, selection, and pagination. Grids are fully keyboard-navigable, and large datasets are virtualized automatically. The body scrolls within a default max height of 30rem; see Large Datasets to change it.
The demo below turns on the most common features at once: sort, filter, search, select, reorder, resize, and paginate. Each is opt-in and covered in its own section below.
Reassign data and columns instead of mutating them.
Both are shallowly reactive, so changing an existing array in place won't re-render. Assign a new array to trigger one.
Examples
Columns
Each column is an object. Use field to map a column to a property on your row objects (dot paths like 'user.name' work too), label for the header text, and align to position cell content. Set width to give a column a fixed pixel width; columns without a width share the remaining space. Text that doesn't fit truncates with an ellipsis, and hovering a truncated cell reveals the full text.
Custom Cell Content
Provide a formatter function to control how a cell renders. It receives the cell value and the full row; return a string for escaped text, or a Lit html template for rich content like badges and buttons. Interpolated values are escaped automatically.
Actions Column
A column doesn't need a field. Give it an id and a formatter to render buttons, links, or menus. With no field, the formatter's first argument is undefined (use the second to reach the row), and the column isn't sortable or searchable. Because these controls render inside cells, give each icon-only button an accessible name, such as the label on its <wa-icon> as in the demo, so assistive technology can tell them apart.
Computed Columns
Give a column a value function to compute its cell value from the row. Unlike a formatter, which only changes how a cell renders, the computed value drives sorting, filtering, searching, copying, and CSV export.
grid.columns = [ { field: 'hours', label: 'Hours' }, { field: 'rate', label: 'Rate' }, { id: 'amount', label: 'Amount', align: 'end', value: row => row.hours * row.rate, formatter: value => currency.format(value), }, ];
Striped Rows
Add the striped attribute for alternating row backgrounds, which can make dense, multi-column grids easier to scan.
Size
Use the size attribute (xs, s, m, l, xl) to control both the grid's text scale and its row height and cell padding together. The size also cascades to the form controls rendered inside the grid (selection checkboxes, the search box, column filters, and the pager).
Appearance
Use the appearance attribute to switch between the default outlined look and a borderless plain look that blends into the surrounding page.
Sorting
Columns with a field are sortable by default; set sortable: false to opt out. Click a header to cycle through ascending, descending, and unsorted, or hold Shift while clicking (or press Shift + Enter on a focused header) to sort by multiple columns, where a numbered badge shows each column's priority. Read or set the order through the sort property, and listen for the wa-sort-change event.
Sort Algorithms
By default, the grid infers a sort algorithm from each column's values, and plain Date objects are detected and sorted chronologically automatically. Set sortFn to pick a specific built-in algorithm, most usefully 'datetime' for columns holding date strings, which would otherwise sort alphabetically:
grid.columns = [ { field: 'name', label: 'Name' }, { field: 'created', label: 'Created', sortable: true, sortFn: 'datetime' }, ];
sortFn accepts any of these built-in algorithms:
sortFn |
Best for | Notes |
|---|---|---|
'alphanumeric' |
Mixed strings and numbers | Case-insensitive |
'alphanumericCaseSensitive' |
Mixed strings and numbers | Case-sensitive |
'text' |
Strings only | Faster than alphanumeric |
'textCaseSensitive' |
Strings only | Faster; case-sensitive |
'datetime' |
Date objects or date strings |
Sorts chronologically |
'basic' |
Simple values | Fastest; plain > / < |
Custom Comparators
For full control, provide a comparator to define your own order, for example, to sort a status column by severity rather than alphabetically. It receives the two cell values (and their rows) and returns a negative, zero, or positive number for ascending order; the grid flips it for descending. A comparator takes precedence over sortFn.
Sort Behavior
A few attributes tune how sorting behaves:
| Attribute | Effect |
|---|---|
without-sort-removal |
A sorted column alternates between ascending and descending instead of clearing its sort on the third click. |
sort-desc-first |
The first click sorts descending. Override per column with sortDescFirst. |
max-multi-sort |
Caps how many columns can multi-sort; adding another drops the oldest. 0 (default) means no limit. |
Per column, sortUndefined controls where empty (null/undefined) values land: 'first', 'last', 1, or -1.
<wa-data-grid without-sort-removal sort-desc-first max-multi-sort="3"></wa-data-grid>
Selection
Add the selectable attribute to render a leading checkbox column with select-all in the header. A bare attribute means selectable="multiple". Set the row-key attribute to a field that uniquely identifies each row so selection stays stable across sorting and pagination. Read the selection from the selectedKeys or selectedRows properties or listen for the wa-row-select event; hold Shift while clicking to select a range.
Selected: 0
When pagination is on, select-all toggles only the current page, leaving other pages' selections intact. To lock specific rows, set the selectableRows property to a predicate. Rows that return false get a disabled checkbox and are skipped by select-all and range selection.
grid.selectableRows = row => row.status !== 'archived';
Set selectable="single" for radio-style selection that allows one row at a time.
Pagination
Add the paginate attribute to break rows into pages with a pager in the footer. Use page-size for rows per page and the pageSizeOptions property for the picker's choices, keeping page-size in that list. The wa-page-change event reports page and pageSize, and the pager is a <wa-pagination> element you can style through the pager part.
The page property is 0-based, so page="0" is the first page. This matches the request payload the grid sends in server mode, but differs from <wa-pagination>, whose page is 1-based.
Global Search
Add the with-search attribute to show a search box that filters across all columns. Listen for the wa-filter-change event to react to the current search term and filters, or read and set the term through the searchTerm property.
Every column with a field (or computed value) participates by default; set searchable: false to exclude one. For custom matching, set the searchFn property to a predicate that receives the cell value, the search term, and the row. A row matches when any searchable column returns true. Read the results with filteredCount, getVisibleRows() (the rows on screen), or getProcessedRows() (every matching row across all pages, sorted).
Column Filters
Set filterable: true on a column to add a filter button to its header. It opens a panel with the column's filter controls, and shows a dot while its filter is active. Column filters and global search can be combined, and the filters property reads or sets the active filters programmatically.
Filter Types
By default a column filter is a case-insensitive substring match. Set filterType to choose a different matcher, each rendering an appropriate panel:
filterType |
Matches | Panel controls |
|---|---|---|
'text' (default) |
case-insensitive substring | a text input |
'equals' |
exact value | a text input |
'number-range' |
values within [min, max] |
min/max number inputs |
'date-range' |
dates within [from, to] (inclusive, by calendar day) |
from/to date inputs |
'set' |
value is one of the checked values | a checkbox list of the column's distinct values, with counts |
'includes-any' |
array-valued cells containing any checked value | a checkbox list of the arrays' distinct values, with row counts |
'includes-all' |
array-valued cells containing every checked value | a checkbox list of the arrays' distinct values, with row counts |
When a value list has more than ten entries, the panel adds a search box to narrow the options. Every panel ends with a Clear button that resets just that column's filter.
For full control, supply a custom filterFn(value, filterValue, row) that returns true to keep a row. It takes precedence over filterType and runs client-side only.
grid.columns = [ { field: 'price', label: 'Under Budget', filterable: true, filterFn: (value, filterValue) => Number(value) <= Number(filterValue), }, ];
Faceted Values
For each column, the grid computes faceted data (the distinct values with counts, and the numeric range) from the rows before that column's own filter is applied. The 'set' filter uses this to populate its options, and you can read it yourself with getColumnFacets(columnId) to build a custom filter UI:
const { uniqueValues, minMax } = grid.getColumnFacets('category'); // uniqueValues: Map { 'Lighting' => 2, 'Textiles' => 2, 'Decor' => 2 } // minMax: undefined (non-numeric); for 'price' it would be [44, 429]
Faceting is client-mode only. In server mode, the server owns filtering, so getColumnFacets returns empty facets and the 'set' filter's panel falls back to a plain text box (range filters keep their controls and pass their bounds to your server).
Column Visibility
Add the with-columns-menu attribute to render a menu that lets users show and hide columns. Set hidden: true on a column to hide it initially, or hideable: false to prevent a column from being toggled. The menu ends with a Reset columns item that restores the default order, widths, visibility, and pinning, also available programmatically as resetColumns(). User-initiated show/hide changes emit wa-column-visibility-change.
Resizing Columns
Add the resizable attribute to let users drag column borders, or set resizable per column. Double-click a handle to auto-size a column to its content, press Alt + Left / Right on a focused header, or call autoSizeColumn(), autoSizeColumns(), or sizeColumnsToFit(). Set a flex ratio on a column to share leftover space proportionally; the wa-column-resize event fires during and after a resize (check detail.finished).
Reordering Columns
Add the reorderable attribute to let users drag column headers to reorder them, or set movable per column to opt individual columns in or out. Focus a header and press Shift + Left / Right to move it from the keyboard. The wa-column-move event fires during the drag and once it settles (check detail.finished); detail.columnOrder holds the new order.
Pinning Columns
Add the pinnable attribute to let columns pin to either edge, where they stay visible while the rest of the grid scrolls horizontally. Click a pinned column's pin icon to unpin it, or set pinnable: false on a column to opt it out. Add the with-column-menu attribute to give each header a menu with pin, sort, hide, and autosize actions.
Start a column pinned with pinned: 'left' (or 'right') in its definition, or pin programmatically with pinColumn() and getColumnPin(); pinning is included in getState() / setState(), and user-initiated pin changes emit the wa-column-pin event. Pinned columns keep their natural order, so pin columns already near their edge. Pinning a column without an explicit width locks in its current width.
Column Footers
Give a column a footer to render a totals row pinned to the bottom of the scroll area. A string renders as escaped text; a function receives the current rows (filtered, across every page), so totals always reflect what the user is looking at.
Columns without a footer leave their footer cell empty, and hiding a column hides its footer with it. The function receives top-level rows for tree data (so parent and child values aren't double-counted), the underlying data rows for grouped grids (not the group headers), and the currently loaded rows in server mode.
Grouping Rows
Set the group-by attribute to a column id to group rows by that column's values; each group renders as an expandable row showing the value and row count. Give other columns an aggregation (sum, min, max, mean, median, count, unique, uniqueCount, extent, or a custom function) to summarize the group on its row. Aggregated values still run through the column's formatter.
Groups behave like tree rows: expand them with the toggle (or Enter on the expand cell), or open everything with expandAllRows(). Checking a group's checkbox selects its members, though selectedKeys only ever contains real rows, never groups. Sorting orders both the groups and their members, filtering regroups the matches, groups paginate as single rows, and CSV export includes the underlying rows without the group headers.
To group by multiple levels, list the columns in the attribute (group-by="department title") or assign an array: grid.groupBy = ['department', 'title']. Grouping is ignored with tree data (child-rows wins) and in server mode.
To render an aggregated cell with full context, give the column an aggregatedFormatter. Unlike formatter, it receives the aggregate value and every data row in the group:
grid.columns = [ { field: 'salary', label: 'Salary', aggregation: 'mean', aggregatedFormatter: (value, rows) => `${currency.format(value)} avg of ${rows.length}`, }, ];
On group rows, use aggregatedFormatter for aggregated cells.
A column's regular formatter receives the group's first row as its second argument (and wa-row-expand / wa-row-collapse report that row too), so it can't see the whole group.
Row Detail Panels
Set the rowDetail property to a function that returns content for an expandable panel. Each row gains an expand toggle, and the wa-row-expand / wa-row-collapse events fire as panels open and close. Panels can be any height, and the grid measures each one to keep virtualized scrolling accurate.
Control expansion programmatically with expandRow(), collapseRow(), expandAllRows(), and collapseAllRows(), or read and assign the full set through the expandedKeys property.
Tree Data
To display hierarchical rows, set the child-rows attribute to the field that holds each row's children (dot paths work too), or set the childRows property to a function for anything more involved. Rows with children get an expand toggle, and expanded children render indented beneath their parent. Adjust the indentation step with the --indent-size custom property.
Sorting orders children within their parent, and pagination keeps an expanded subtree on its parent's page. With multiple selection, checking a parent checks all of its descendants (even collapsed ones), a partially selected parent shows an indeterminate checkbox, and select-all reaches into collapsed subtrees too.
When filtering tree data, a row that doesn't match is removed along with its entire subtree. Add the filter-from-leaf-rows attribute to run filters (including the global search) from the leaves up instead, so a parent stays visible whenever any of its descendants match.
Press Enter on a row's expand cell to toggle it from the keyboard. wa-row-expand and wa-row-collapse fire only when the user toggles a row. Programmatic calls like expandRow() don't emit events.
In server mode, child-rows still works when your rows arrive with their children nested, but the request object carries no expansion information, so the grid doesn't lazy-load children on expand.
With tree data, the grid switches to the ARIA treegrid role, and rows report aria-level and aria-expanded. Announced row counts cover only the visible rows, since expanding and collapsing changes what's on screen.
Empty & Loading States
When there are no rows to display, the grid shows a default empty message. Provide your own content in the empty slot to give users guidance or a call to action. When an active search or filter matches nothing, the grid shows a distinct "no results" message instead. Customize it with the no-results slot.
Create your first invoice to see it here.
While a server-mode request is in flight, the grid sets its loading attribute and shows a translucent overlay with a spinner. Slot your own content into the loading slot to customize it:
<wa-data-grid label="Orders"> <div slot="loading" class="wa-stack wa-align-items-center"> <wa-spinner style="font-size: 2rem;"></wa-spinner> <small>Loading orders…</small> </div> </wa-data-grid>
Large Datasets & Virtualization
Rows are virtualized automatically. Only the visible window (plus a small overscan) exists in the DOM, so tens of thousands of rows scroll smoothly without pagination. The body scrolls within a max height of 30rem by default; set the --max-height custom property to change it, or to none to let the grid grow with its content. Call scrollToIndex(index) to jump to a row programmatically.
Keep a bounded height for very large datasets.
Virtualization works because the grid's body has a fixed max height. Setting --max-height: none makes the page scroll instead and renders every row, so keep the default (or any fixed value).
Loading Data from a Server
For large or remote datasets, set the dataSource property to an async function. The grid switches to server mode, where sorting, filtering, and pagination become your server's job, and calls dataSource whenever they change. Return the current page of rows and the total row count; the loading property reflects whether a request is in flight.
Each request carries an AbortSignal that you forward to your fetch(). The grid aborts the previous request and ignores out-of-order responses, so rapid changes can't show stale data. Search and filter keystrokes are debounced (250ms by default; tune with the filter-debounce attribute), and reload() re-runs the current request at any time.
If a dataSource request rejects, the grid keeps the previous rows, emits wa-data-error with the error and the failed request, and logs to the console. Listen for it to show a toast or a retry action:
grid.addEventListener('wa-data-error', event => { console.error(event.detail.error); // Offer a retry: // grid.reload(); });
Event-Driven Server Mode
If you prefer to manage fetching yourself, or you're not using JavaScript callbacks at all, add the server attribute instead of setting dataSource. The grid disables client-side sorting, filtering, and pagination and emits wa-data-request whenever it needs data; fetch in your handler, then set data, total, and loading:
<wa-data-grid server paginate label="Orders"></wa-data-grid> <script type="module"> const grid = document.querySelector('wa-data-grid'); grid.addEventListener('wa-data-request', async event => { const { sort, filters, search, page, pageSize, signal } = event.detail; grid.loading = true; try { const response = await fetch(`/api/orders?page=${page}&size=${pageSize}&q=${search}`, { signal }); const { rows, total } = await response.json(); grid.data = rows; grid.total = total; } finally { grid.loading = false; } }); </script>
Responding to Cell Clicks
The grid emits wa-cell-click when a data cell is clicked or Enter is pressed on the active cell. Its detail carries the column id, the cell value, the row object, and the row's display index, enough to open a record, copy a value, or drive a master–detail view without wiring listeners inside formatters.
Right-clicks (and Shift + F10 on the active cell) emit wa-cell-contextmenu with the same payload plus the originalEvent. Cancel the event to suppress the browser's native menu and show your own:
grid.addEventListener('wa-cell-contextmenu', event => { event.preventDefault(); // suppress the native context menu openMyMenu(event.detail.row, event.detail.originalEvent); });
Copying to the Clipboard
Press Ctrl + C (or Cmd + C) with rows selected to copy them, or call copySelectedRows() yourself, which copies every processed row when nothing is selected. The default tab-separated format pastes straight into spreadsheet cells; pass format: 'csv' for comma-separated text. The copy honors the active sort, filters, and column visibility and order.
CSV Export
Call grid.exportDataAsCsv() to download the current rows as a CSV file, or getDataAsCsv() to get the text without a download. The export respects the active sort, filters, search, and column visibility and order, applying each formatter that returns a string (rich-template formatters fall back to the raw value). It includes every page and every tree depth, expanded or not; in server mode, only the currently loaded page is exported.
Exporting user-generated data to a spreadsheet? Pass escapeFormulas: true.
It neutralizes cells that would otherwise execute as formulas (values starting with =, +, -, or @); plain numbers are left untouched.
Saving & Restoring State
Call grid.getState() for a serializable snapshot of the column order, widths, visibility, pinning, sort, filters, search, selection, expansion, and paging, and pass it back to grid.setState() to restore it, for example from localStorage. Use resetState() to return the view (including expansion) to the column defaults, leaving selection and paging untouched. On a grouped grid, the snapshot's expandedKeys include group ids, so they only restore meaningfully while group-by stays the same.
Keyboard Navigation
The grid follows the ARIA grid pattern. The whole grid is a single tab stop; once focused, navigate cells with the keyboard:
- Up Down Left Right — move between cells (and into the header)
- Home / End — first / last cell in the row
- Ctrl + Home / End — first / last cell in the grid
- Page Up / Page Down — move by a page of rows
- Enter — sort the focused header column, toggle expansion from a row's expand cell, or activate a data cell (emits
wa-cell-click) - Space — toggle selection of the focused row
- Shift + Up / Down — extend the selection
- Ctrl + A — select all rows (the current page's rows when paginated)
- Ctrl + C — copy the selected rows
- Shift + F10 — open the context menu for the focused cell (emits
wa-cell-contextmenu) - Shift + Left / Right — reorder the focused header column
- Alt + Left / Right — resize the focused header column
Preloading Rendered Components
A formatter's content renders inside the grid's shadow DOM, where Web Awesome's autoloader can't see it, because its observer only watches the main document. A component rendered only by a formatter may never register, leaving cells empty or unstyled.
To avoid this, register every component your formatters render up front. If you import Web Awesome components individually, import the registration module for each one:
import '@awesome.me/webawesome/dist/components/avatar/avatar.js'; import '@awesome.me/webawesome/dist/components/badge/badge.js'; import '@awesome.me/webawesome/dist/components/rating/rating.js';
If you rely on the autoloader, list the components your formatters use in a space-separated data-wa-preload attribute. <html> (or <body>) is the most robust spot since it registers regardless of when the grid mounts, but any element in the main document works, including the grid itself:
<html data-wa-preload="wa-avatar wa-badge wa-rating"> <!-- … --> </html>
This applies to anything rendered into the grid's shadow DOM: formatters, row detail panels, and your own custom elements alike. Components placed directly in your HTML (such as the empty and loading slots) live in the main document and autoload normally.
Styling Rendered Components
As with preloading, formatter content lives in the grid's shadow DOM, so page-level CSS can't reach it. To apply custom styles to the components your formatters render, across every row at once, adopt a stylesheet into the grid's shadow root:
const grid = document.querySelector('#grid'); const sheet = new CSSStyleSheet(); sheet.replaceSync(` .row-badge::part(base) { text-transform: uppercase; letter-spacing: 0.05em; } `); grid.shadowRoot.adoptedStyleSheets = [...grid.shadowRoot.adoptedStyleSheets, sheet];
Give the components you render a class (or data attribute) in your formatter so the stylesheet can target them:
grid.columns = [ { field: 'status', label: 'Status', formatter: value => html`<wa-badge class="row-badge" variant="success">${value}</wa-badge>`, }, ];
To style whole rows conditionally, set the rowClass property to a function that returns class names per row, and target them from the same adopted stylesheet:
grid.rowClass = row => (row.overdue ? 'overdue' : null); sheet.replaceSync(`.row.overdue { background-color: var(--wa-color-danger-fill-quiet); }`);
Always scope these selectors to a unique class or data attribute of your own (like .row-badge above). The grid's shadow root uses Web Awesome class names and CSS parts for its own markup, so broad selectors such as wa-badge, ::part(base), or .cell collide with those internals and can break the grid's appearance.
Theming
The grid exposes a curated set of CSS custom properties for theming: --accent-color drives the checkboxes and pinned-column highlights, and the rest tune backgrounds, borders, spacing, and the scroll area's --max-height. Each defaults to a Web Awesome design token, so grids adapt to light and dark themes automatically.
When theming with a raw palette color, mix it with a neutral surface or text token (as below) so the result follows the surface between light and dark themes. This example tints every customizable region with the same purple; the effect shows on row hover, selection, and keyboard focus.
Accessibility Considerations
Always give the grid an accessible name with the label attribute. The grid uses the ARIA grid role (or treegrid when rows form a hierarchy) with row and column indices, sort state, selection state, and expansion state on the underlying cells, so assistive technology can navigate and announce it like a native table.
Screen readers are kept in the loop as things change: a polite live region announces selection counts, filter results, clipboard copies, and column moves, and every control the grid renders (checkboxes, expand toggles, filter buttons and panels, menus, the pager) carries an accessible name that's localized along with the rest of Web Awesome's translations.
API
Importing
If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.
Import this component directly from the CDN:
import 'https://ka-f.webawesome.com/[email protected]/components/data-grid/data-grid.js';
After installing Web Awesome via npm, import this component:
import '@awesome.me/webawesome/dist/components/data-grid/data-grid.js';
If you're self-hosting Web Awesome, import this component from your server:
import './webawesome/dist/components/data-grid/data-grid.js';
To import this component for React 18 or below, use the following code:
import WaDataGrid from '@awesome.me/webawesome/dist/react/data-grid/index.js';
Slots
Learn more about using slots.
| Name | Description |
|---|---|
empty
|
Content shown when there are no rows to display. |
loading
|
Content shown in the loading overlay (server mode). |
no-results
|
Content shown when an active search or filter matches no rows (falls back to a localized message). |
Attributes & Properties
Learn more about attributes and properties.
| Name | Description | Reflects |
|---|---|---|
appearanceappearance |
The grid's visual appearance.
Type
'outlined' | 'plain'
Default
'outlined'
|
|
childRowschild-rows |
Provides each row's child rows for tree data — a field name (dot paths allowed) or a function returning children.
Rows with children get an expand toggle; expanded children render indented and join sorting/filtering/selection.
Type
string | ((row: Row) => Row[] | undefined) | null
Default
null
|
|
columnOrder |
Get/set the column display order as an array of column ids. Empty array = natural order.
Type
string[]
|
|
columns |
The column definitions.
Type
DataGridColumn[]
Default
[]
|
|
data |
The row objects to display. In client mode this is the full set.
Type
Row[]
Default
[]
|
|
dataSource |
An async function that loads data from a server. When set, the grid switches to manual mode: client-side
sorting/filtering/pagination are disabled and this runs on any sort/filter/search/page change. Return
rows and
total.
Type
((request: DataGridRequest) => Promise<DataGridResponse>) | null
Default
null
|
|
expandedKeys |
The row keys of the currently expanded rows. Settable. Without a
row-key, ids follow table-core's convention:
a top-level row's index ('0'), then dotted index paths for children ('0.1').
Type
(string | number)[]
|
|
filterDebouncefilter-debounce |
How long (in milliseconds) to wait after a search or filter keystroke before requesting data in server mode.
Client-side filtering is always immediate. Sort and page changes are never debounced.
Type
number
Default
250
|
|
filteredCount |
The number of rows in the current result set after filtering and search, across every page (top-level rows for
tree and grouped data; the server-reported
total in server mode). Read-only.
Type
number
|
|
filterFromLeafRowsfilter-from-leaf-rows |
When filtering tree data, keeps a parent visible when any descendant matches (the filter runs leaf-up). By default
a non-matching parent is removed with its entire subtree.
Type
boolean
Default
false
|
|
filters |
Get/set the column filters declaratively, e.g.
[{ id: 'category', value: 'Lighting' }].
Type
{ id: string; value: unknown }[]
|
|
groupBygroup-by |
Groups rows by column id — a single id, a space/comma-separated list (or array) for multi-level grouping. Each
group is an expandable row showing its value, member count, and any column aggregates. Ignored for tree data and
in server mode.
Type
string | string[] | null
Default
null
|
|
labellabel |
An accessible label for the grid.
Type
string | null
Default
null
|
|
loadingloading |
Whether a
dataSource request is in flight.
Type
boolean
Default
false
|
|
maxMultiSortmax-multi-sort |
The maximum number of columns that can participate in a multi-column sort.
0 (default) means no limit.
Type
number
Default
0
|
|
pagepage |
The current page index (0-based).
Type
number
Default
0
|
|
pageCount |
The number of pages in the current result set (always
1 when paginate is off). Read-only.
Type
number
|
|
pageSizepage-size |
The number of rows per page.
Type
number
Default
20
|
|
pageSizeOptions |
The page sizes offered by the pager's page-size selector.
Type
number[]
Default
[10, 20, 50, 100]
|
|
paginatepaginate |
Enables client-side pagination and the pager footer.
Type
boolean
Default
false
|
|
pinnablepinnable |
Enables column pinning (and the pin actions in the column menu). Can be overridden per column with
pinnable.
Type
boolean
Default
false
|
|
reorderablereorderable |
Enables drag-to-reorder for columns (can be overridden per column with
movable).
Type
boolean
Default
false
|
|
resizableresizable |
Enables drag-to-resize for columns (can be overridden per column).
Type
boolean
Default
false
|
|
rowClass |
Returns extra CSS class names for a row (space-separated; falsy for none) — e.g. to flag overdue or archived
rows. Classes land on the row element inside the grid's shadow root, so style them with an adopted stylesheet
(see the docs' "Styling Rendered Components"). Group rows are skipped.
Type
((row: Row) => string | null | undefined) | null
Default
null
|
|
rowDetail |
Renders an expandable detail panel for a row. When set, each row shows an expand toggle. Return a string (escaped
text), a Lit
TemplateResult, or a Node.
Type
((row: Row) => string | TemplateResult | Node) | null
Default
null
|
|
rowKeyrow-key |
The field used as a stable row id for selection. Required in practice when
selectable is set.
Type
string | null
Default
null
|
|
searchFn |
A custom predicate for the global search box. Receives the cell value, the search term, and the row; return
true to keep the row (a row matches when any searchable column matches). Client mode only.
Type
((value: unknown, searchTerm: string, row: Row) => boolean) | null
Default
null
|
|
searchTerm |
The current global search term.
Type
string
Default
''
|
|
selectableselectable |
Enables row selection. A bare attribute means
multiple.
Type
'' | 'single' | 'multiple' | 'none'
Default
'none'
|
|
selectableRows |
A predicate deciding whether a row can be selected. Return
false to lock a row: its checkbox is disabled and it's
skipped by select-all and range selection. When unset, every row is selectable (subject to selectable).
Type
((row: Row) => boolean) | null
Default
null
|
|
selectedKeys |
The
rowKey values of the currently selected rows. The source of truth for selection.
Type
(string | number)[]
|
|
selectedRows |
The selected row objects resolvable from the currently loaded
data (best-effort, any tree depth). Settable,
resolved by key.
Type
Row[]
|
|
serverserver |
Switches the grid to server mode without a
dataSource callback: client-side sorting, filtering, and pagination
are disabled and the grid emits wa-data-request whenever it needs data. Listen for it, fetch, then set data,
total, and loading yourself. Implied when dataSource is set.
Type
boolean
Default
false
|
|
sizesize |
The grid's size. Controls the font scale of grid text and form controls, plus row height and cell padding.
Type
'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large'
Default
'm'
|
|
sort |
Get/set the sort state declaratively, e.g.
[{ id: 'name', desc: false }].
Type
SortingState
|
|
sortDescFirstsort-desc-first |
When
true, a column's first sort click sorts descending instead of ascending (table-core sortDescFirst).
Type
boolean
Default
false
|
|
stripedstriped |
Renders alternating row background colors.
Type
boolean
Default
false
|
|
totaltotal |
The total row count in server mode. Drives the pager. Set automatically when
dataSource resolves.
Type
number
Default
-1
|
|
withColumnMenuwith-column-menu |
Shows a per-column header menu (kebab button) with pin, sort, hide, and autosize actions.
Type
boolean
Default
false
|
|
withColumnsMenuwith-columns-menu |
Shows a toolbar menu for toggling column visibility.
Type
boolean
Default
false
|
|
withoutSortRemovalwithout-sort-removal |
Keeps a sorted column always sorted, alternating between ascending and descending. By default, a sorted column's
third click clears its sort (the asc → desc → unsorted cycle).
Type
boolean
Default
false
|
|
withSearchwith-search |
Shows a global search box that filters across all columns.
Type
boolean
Default
false
|
|
Methods
Learn more about methods.
| Name | Description | Arguments |
|---|---|---|
autoSizeColumn() |
Resizes one column to fit its widest rendered cell content (the double-click-handle behavior). |
columnId: string
|
autoSizeColumns() |
Resizes every resizable column to fit its content. | |
collapseAllRows() |
Collapses every row. | |
collapseRow() |
Collapses the row with the given key (its rowKey value). |
key: string | number
|
copySelectedRows() |
Copies the selected rows (or every processed row when nothing is selected) to the clipboard, honoring the active
sort, filters, and column visibility/order. The default tab-separated format pastes into spreadsheet cells;
format: 'csv' copies comma-separated text instead. Also wired to Ctrl+C when the grid has focus.
Returns the number of rows copied. |
options: {
columnIds?: string[];
includeHeaders?: boolean;
format?: 'tsv' | 'csv';
escapeFormulas?: boolean;
}
|
expandAllRows() |
Expands every row (all detail panels, or every branch of a tree). | |
expandRow() |
Expands the row with the given key (its rowKey value). |
key: string | number
|
exportDataAsCsv() |
Exports the current rows as a CSV file (browser download). Respects the active sort, filters, search, and column
visibility/order, and runs each column's formatter. In server mode, only the currently loaded page is exported. |
options: {
fileName?: string;
columnIds?: string[];
includeHeaders?: boolean;
delimiter?: string;
escapeFormulas?: boolean;
}
|
focus() |
Focuses the grid by focusing the active (roving-tabindex) cell. |
options: FocusOptions
|
getColumnFacets() |
Faceted data for a column — distinct cell values (with counts) and the numeric min/max, computed before this column's own filter applies. Use it to build filter UIs. Client mode only; returns empty facets in server mode. |
columnId: string
|
getColumnPin() |
Returns which edge a column is pinned to, or false if it isn't pinned. |
columnId: string
|
getDataAsCsv() |
Returns the current rows as a CSV string, honoring the active sort, filters, search, and column visibility/order.
Each column's formatter runs for string output only (TemplateResult/Node cells fall back to the raw value).
Every page and tree depth is included; server mode exports only the loaded page. Set escapeFormulas: true when
the file may open in a spreadsheet and the data isn't trusted — cells starting with =, +, -, or @ are
prefixed with an apostrophe so they can't execute as formulas (plain numbers are left alone). |
options: {
columnIds?: string[];
includeHeaders?: boolean;
delimiter?: string;
escapeFormulas?: boolean;
}
|
getProcessedRows() |
Every data row in the current result set, in display order — after sorting, filtering, and search, across all pages and tree depths (parents before their children). Group header rows are excluded. In server mode this is the currently loaded page. | |
getState() |
Returns a serializable snapshot of column order, widths, visibility, sort, filters, search, selection, paging. | |
getVisibleRows() |
The data rows currently displayed, in display order — after sorting, filtering, expansion, and pagination. Group header rows are excluded. | |
handleColumnsChange() |
When the columns change, prune any persisted order/sizing/visibility for column ids that no longer exist, and append newly-added column ids to the end of the order so they remain visible. | |
handlePageChange() |
Reacts to page changes from ANY source — pager clicks and programmatic sets alike — so grid.page = 3 clamps,
keeps the roving tab stop in range, and refetches in server mode. UI paths that already requested data are
deduped by the fetch scheduler. |
|
handleSearchTermChange() |
Reacts to searchTerm changes from any source: returns to the first page, keeps the tab stop in range, and
refetches (debounced) in server mode. The UI input handler only sets the property and emits — the behavior
lives here so programmatic sets act exactly like typing. |
|
pinColumn() |
Pins a column to the 'left' or 'right' edge, or unpins it with false. |
columnId: string,
side: 'left' | 'right' | false
|
reload() |
Re-runs the current server request (server mode only), even if its parameters haven't changed. | |
resetColumns() |
Resets column order, widths, visibility, and pinning to the column definitions' defaults, leaving sort, filters, search, selection, and paging untouched (the columns menu's "Reset columns" action). | |
resetState() |
Resets all user-adjusted view state (order, widths, visibility, pinning, sort, filters, search, expansion) to the column defaults. Selection and paging are left alone — clearing a user's selection is destructive. | |
scrollToIndex() |
Scrolls the row at the given display index into view (pairs with virtualization). |
index: number,
options: { align?: 'start' | 'center' | 'end' }
|
setState() |
Restores a previously captured state. Unknown column ids are ignored; omitted keys are left unchanged. |
state: DataGridState
|
sizeColumnsToFit() |
Distributes column widths to fill the available horizontal space, honoring each column's min/max. | |
toggleColumn() |
Shows or hides a column by its id (the column's id, or field when no id is set). |
columnId: string,
visible: boolean
|
Events
Learn more about events.
| Name | Description |
|---|---|
request |
|
wa-cell-click |
Emitted when a data cell is clicked, or Enter is pressed on the active data cell. |
wa-cell-contextmenu |
Emitted when a data cell is right-clicked (or Shift+F10 / the menu key is pressed on the active cell). Cancel it to suppress the native context menu. |
wa-column-move |
Emitted when a column is reordered (live during drag; check detail.finished). |
wa-column-pin |
Emitted when the user pins or unpins a column through the built-in controls. Programmatic pinColumn() calls don't emit. |
wa-column-resize |
Emitted when a column is resized (live during drag; check detail.finished). |
wa-column-visibility-change |
Emitted when the user shows or hides a column through the built-in menus. Programmatic toggleColumn() calls don't emit. |
wa-data-error |
Emitted in server mode when a dataSource request rejects. |
wa-data-request |
Emitted in server mode when the grid needs data for the current sort, filters, and page. |
wa-filter-change |
Emitted when the global search or a column filter changes. |
wa-page-change |
Emitted when the current page or page size changes. |
wa-row-collapse |
Emitted when a row collapses (a detail panel or a tree row's children). |
wa-row-expand |
Emitted when a row expands (a detail panel or a tree row's children). |
wa-row-select |
Emitted when the row selection changes. |
wa-sort-change |
Emitted when the sort order changes. |
CSS Custom Properties
Learn more about CSS custom properties.
| Name | Description |
|---|---|
--accent-color |
The checkbox accent and pinned-column highlight.
Default
var(--wa-color-brand-fill-loud)
|
--background-color |
The grid body background.
Default
var(--wa-color-surface-default)
|
--border-color |
The gridline and outer border color.
Default
var(--wa-color-surface-border)
|
--border-radius |
The outer corner radius (outlined appearance).
Default
var(--wa-border-radius-m)
|
--border-width |
The gridline thickness.
Default
var(--wa-border-width-s)
|
--cell-padding |
The cell inline padding (also set by
size).
Default
var(--wa-space-m)
|
--focus-ring |
The active-cell focus ring.
Default
var(--wa-focus-ring)
|
--header-background |
The header row background.
Default
var(--wa-color-surface-lowered)
|
--header-row-height |
The height of the header row.
Default
var(--row-height)
|
--header-text-color |
The header text color.
Default
var(--wa-color-text-normal)
|
--indent-size |
The indentation applied per depth level to child rows in tree data.
Default
1.25em
|
--max-height |
The maximum height of the scrollable body. Set
none for natural height.
Default
30rem
|
--row-height |
The height of each row (also set by
size).
Default
3.5rem
|
--row-hover-background |
The hovered row background.
Default
var(--wa-color-neutral-fill-normal)
|
--selected-background |
The selected row background.
Default
var(--wa-color-brand-fill-quiet)
|
--stripe-background |
The zebra (odd row) background.
Default
var(--wa-color-neutral-fill-quiet)
|
--text-color |
The cell text color.
Default
var(--wa-color-text-normal)
|
--transition-duration |
The reorder/resize transition duration.
Default
var(--wa-transition-normal)
|
CSS Parts
Learn more about CSS parts.
| Name | Description | CSS selector |
|---|---|---|
body |
The scrollable body container. |
::part(body)
|
cell |
A data cell. |
::part(cell)
|
column-menu |
The per-column header options dropdown. |
::part(column-menu)
|
column-menu-button |
The kebab button that opens a column's options menu. |
::part(column-menu-button)
|
columns-menu |
The column visibility menu. |
::part(columns-menu)
|
data-grid |
The component's outer wrapper. |
::part(data-grid)
|
drag-ghost |
The floating label that follows the pointer while reordering a column (rendered in the top layer). |
::part(drag-ghost)
|
ellipsis |
The collapsed-pages ellipsis in the pager. |
::part(ellipsis)
|
empty |
The empty-state container shown when there are no rows (wraps the empty slot). |
::part(empty)
|
expand-button |
The expand/collapse toggle button on a row. |
::part(expand-button)
|
filter-button |
The funnel button in a filterable column's header that opens its filter panel. |
::part(filter-button)
|
filter-panel |
The popover panel that contains a column's filter controls. |
::part(filter-panel)
|
first-button |
The "first page" pager button. |
::part(first-button)
|
footer |
The footer that contains the pager. |
::part(footer)
|
footer-cell |
A column footer cell. |
::part(footer-cell)
|
footer-row |
The column footer row pinned to the bottom of the scroll area. |
::part(footer-row)
|
group-count |
The member count shown next to a group's value. |
::part(group-count)
|
group-row |
A group row (also carries row), when group-by is set. |
::part(group-row)
|
group-value |
The group's value in a group row's grouping cell. |
::part(group-value)
|
header |
The header row container. |
::part(header)
|
header-cell |
A column header cell. |
::part(header-cell)
|
last-button |
The "last page" pager button. |
::part(last-button)
|
live-region |
The visually-hidden polite live region for screen-reader announcements. |
::part(live-region)
|
loading-overlay |
The overlay shown while a server request is in flight. |
::part(loading-overlay)
|
next-button |
The "next page" pager button. |
::part(next-button)
|
no-results |
The container shown when a search or filter matches no rows (wraps the no-results slot). |
::part(no-results)
|
page |
A page-number button in the pager. |
::part(page)
|
page-current |
The current page-number button in the pager. |
::part(page-current)
|
page-size |
The page-size <wa-select> in the footer. |
::part(page-size)
|
pager |
The pagination control (a <wa-pagination> element). |
::part(pager)
|
pager-button |
Every button in the pager, including page numbers (exported from wa-pagination's button part). |
::part(pager-button)
|
pin-indicator |
The pin button shown in a pinned column's header (click to unpin). |
::part(pin-indicator)
|
previous-button |
The "previous page" pager button. |
::part(previous-button)
|
resize-handle |
The drag handle for resizing a column. |
::part(resize-handle)
|
row |
A data row. |
::part(row)
|
row-detail |
The expandable detail panel for a row. |
::part(row-detail)
|
search |
The global search input. |
::part(search)
|
select-all-checkbox |
The header checkbox that selects the current page. |
::part(select-all-checkbox)
|
sort-indicator |
The sort direction arrow icon in a header cell. |
::part(sort-indicator)
|
sort-number |
The numbered priority badge shown next to each column in a multi-column sort. |
::part(sort-number)
|
table |
The grid table element. |
::part(table)
|
toolbar |
The toolbar that contains the search box and columns menu. |
::part(toolbar)
|
Dependencies
This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.
<wa-button><wa-checkbox><wa-divider><wa-dropdown><wa-dropdown-item><wa-icon><wa-input><wa-option><wa-pagination><wa-popup><wa-select><wa-spinner><wa-tag>