The definitions for the columns to be rendered. This defines the field mapping, titles, sortability, and other static options.
The dynamic runtime state of the table's columns (visibility, width, and sort order).
Unlike the static columns definitions, columnStates represents the current,
interactive state of the grid. This is primarily used for programmatic control,
or for saving and restoring user preferences (e.g., from localStorage).
The array of data objects to be displayed.
Objects must satisfy the WeakKey constraint (objects only, no primitives).
ReadonlydisplayThe computed, fully-resolved array of columns intended for visual rendering.
This is a derived View Model. It takes the explicit columnOrder intent and
reconciles it against the actual columns definitions. It safely handles newly
added columns, filters out undefined fields, and guarantees a strictly-typed array
representing the exact left-to-right visual layout of the data grid.
This property is intended for template rendering and internal layout math
(such as drag-and-drop boundary calculations). To programmatically mutate the column
layout, set the columnOrder property or use the moveColumn() API.
An optional set of criteria to filter the visible rows. This runs before the global search query is applied. *
An optional custom filter function. Provide this function to bypass the default filter logic.
controller.filterStrategy = (row, filters) => {
// Example: Custom global search across multiple columns
if (filters.globalSearch) {
const term = filters.globalSearch.toLowerCase();
if (
!row.firstName.toLowerCase().includes(term) &&
!row.lastName.toLowerCase().includes(term)
) {
return false;
}
}
// Example: Strict mathematical matching
if (filters.minAge && row.age < filters.minAge) {
return false;
}
return true;
};
OptionalrowA callback function used to extract or generate a unique identifier for each row.
A stable, unique ID is heavily relied upon by the grid engine for maintaining row selection state, tracking row metadata, and ensuring optimal rendering performance within the virtual scroller—especially when data is actively being sorted, filtered, or updated.
Default Behavior: * If not provided, the table will automatically attempt to locate an id, key, or _id
property on the row data object. If none are found, it falls back to using the row's original
array index (which will trigger a console warning, as indices are inherently unstable during sorting).
Note: Because this expects a JavaScript function, it is exposed strictly as a property
and does not have a corresponding HTML attribute. You must use the property binding syntax
(.rowIdCallback) in a Lit template.
The row selection method to use.
Enables weighted relevance scoring for search results. When enabled, exact matches and prefix matches are ranked higher than substring matches. Rows are sorted by their relevance score descending.
The current text string used to filter the table data. Setting this property triggers a new search and render cycle.
A function that splits the search query into tokens. Only used if search tokenization is enabled.
List of currently selected row indexes.
Configuration options for automatically saving and restoring table state (column width, order, visibility, etc.) to the provided storage interface.
Enables tokenized search behavior.
When enabled, the search query is split into individual tokens using the
searchTokenizer function (defaults to splitting on whitespace).
A row is considered a match if ANY of the tokens appear in the searchable fields.
The explicit, raw visual layout intent for the table's columns. This property acts as the pure state record. It is strictly symmetrical: reading this property will return the exact array of field names that was most recently set, preserving the user's or developer's exact layout preference.
localStorageor a database).