Overview
The <web-grid> web component provides a high-performance data grid with editing, sorting, pagination, and Excel-like navigation.
Core Properties
| Property | Type | Default | Description |
|---|---|---|---|
items | T[] | [] | Array of data objects to display |
columns | Column<T>[] | [] | Column definitions (see Columns API) |
mode | 'read-only' | 'excel' | 'input-matrix' | - | Grid mode - sets sensible defaults for common use cases |
Basic Setup
Display Properties
| Property | Type | Default | Description |
|---|---|---|---|
striped | boolean | false | Alternating row background colors |
hoverable | boolean | false | Highlight rows on hover |
showRowNumbers | boolean | false | Show row number column on the left |
class | string | - | Custom CSS class(es) on host element |
style | string | - | Inline styles on host element |
Sorting Properties
| Property | Type | Default | Description |
|---|---|---|---|
sortMode | 'none' | 'single' | 'multi' | 'none' | Sorting mode: disabled, single column, or multi-column with Ctrl+Click |
sort | SortState[] | [] | Current sort state (for initial/controlled sort) |
Sort State
Pagination Properties
| Property | Type | Default | Description |
|---|---|---|---|
pageable | boolean | false | Enable pagination |
pageSize | number | 10 | Items per page |
currentPage | number | 1 | Current page (1-based) |
totalItems | number | - | Total items (for server-side pagination) |
pageSizes | number[] | [10, 25, 50, 100] | Available page size options |
showPagination | boolean | 'auto' | 'auto' | When to show: true=always, false=never, 'auto'=hide when 1 page |
paginationPosition | string | 'bottom-center' | Position(s): "bottom-center", "top-right|bottom-right" |
paginationLayout | string | - | Element order: "pageSize|previous|pageInfo|next" |
paginationLabelsCallback | function | - | Callback to customize pagination text |
Editing Properties
| Property | Type | Default | Description |
|---|---|---|---|
editable | boolean | false | Enable editing on all columns with editors |
editTrigger | EditTrigger | 'click' | How editing is triggered: 'click', 'dblclick', 'button', 'always', 'navigate' |
dropdownToggleVisibility | 'always' | 'on-focus' | 'on-focus' | When to show dropdown toggle button |
openDropdownOnEnter | boolean | false | Enter opens dropdown (true) or moves down (false) |
checkboxAlwaysEditable | boolean | false | Make checkboxes always interactive |
invalidCells | CellValidationState[] | [] | Currently invalid cells (for external tracking) |
Row Toolbar Properties
| Property | Type | Default | Description |
|---|---|---|---|
showRowToolbar | boolean | false | Enable row toolbar |
rowToolbar | RowToolbarConfig[] | [] | Toolbar items: strings ('add', 'delete', etc.) or custom objects |
toolbarTrigger | 'hover' | 'click' | 'button' | 'hover' | How to show toolbar |
toolbarPosition | 'auto' | 'left' | 'right' | 'top' | 'inline' | 'auto' | Toolbar position. 'inline' renders as fixed column |
toolbarVerticalAlign | 'top' | 'center' | 'bottom' | 'bottom' | Vertical alignment of toolbar rows |
toolbarHorizontalAlign | 'start' | 'center' | 'end' | 'cursor' | 'center' | Horizontal alignment (for top position) |
inlineActionsTitle | string | '' | Column header for inline toolbar mode |
Keyboard Shortcuts Properties
| Property | Type | Default | Description |
|---|---|---|---|
rowShortcuts | RowShortcut[] | [] | Keyboard shortcuts for row operations (work on focused or hovered row) |
showShortcutsHelp | boolean | false | Show info icon with available shortcuts overlay |
shortcutsHelpPosition | 'top-right' | 'top-left' | 'top-right' | Position of shortcuts help icon |
shortcutsHelpContentCallback | () => string | - | Custom HTML content for shortcuts overlay |
Row Shortcuts
Labels/i18n Properties
| Property | Type | Description |
|---|---|---|
labels | Partial<GridLabels> | Translatable UI strings (merged with defaults) |
Labels Configuration
Virtual Scroll Properties
| Property | Type | Default | Description |
|---|---|---|---|
virtualScroll | boolean | false | Enable virtual scrolling |
virtualScrollThreshold | number | 100 | Auto-enable when items >= threshold |
virtualScrollRowHeight | number | 38 | Fixed row height in pixels |
virtualScrollBuffer | number | 10 | Extra rows above/below viewport |
infiniteScroll | boolean | false | Enable infinite scroll (load more) |
infiniteScrollThreshold | number | 100 | Pixels from bottom to trigger load |
hasMoreItems | boolean | true | Set to false when no more data |
Context Menu & Summary
| Property | Type | Default | Description |
|---|---|---|---|
contextMenu | ContextMenuItem[] | - | Right-click menu items (supports shortcut property) |
contextMenuXOffset | number | 8 | Horizontal offset from click position (pixels) |
contextMenuYOffset | number | 0 | Vertical offset from click position (pixels) |
summaryPosition | string | - | Position(s): "bottom-left", "top-right|bottom-right" |
summaryContentCallback | function | - | Callback returning HTML content for summary |
summaryInline | boolean | true | Share row with pagination |
Row Locking Properties
Lock rows to prevent editing (useful for collaborative scenarios).
| Property | Type | Description |
|---|---|---|
idValueMember | string | Property name for row ID (e.g., 'id') |
idValueCallback | (row) => unknown | Callback to compute row ID |
rowLocking | RowLockingOptions | Row locking configuration (see below) |
Row Locking
Styling Callbacks
| Property | Type | Description |
|---|---|---|
customStylesCallback | () => string | Return custom CSS to inject into shadow DOM |
rowClassCallback | (row, rowIndex) => string | null | Dynamic CSS class for rows |
Styling Callbacks
Grid Modes
The mode property sets sensible defaults for common use cases:
read-only
Display-only grid. Editing disabled, optimized for viewing data.
excel
Excel-like behavior. Navigate mode with arrow keys, type to edit, Enter/Tab to commit.
input-matrix
Form-like behavior. All cells editable, Tab moves between cells.
Grid Mode
TypeScript Support
The component is fully typed with generic support:
TypeScript Example
Global API
Access component functionality through window.keenmate.grid:
| Method / Property | Returns | Description |
|---|---|---|
version() | string | Returns the component version |
config | object | Package metadata (name, version, author, etc.) |
register() | void | Manually register the custom element |
getInstances() | HTMLElement[] | Get all active grid instances on the page |
Global API Usage
Important Notes
- Generic Types: Component supports any data structure via
Tparameter - Reactive: All properties are reactive - changes update the UI automatically
- Shadow DOM: Component uses Shadow DOM for style encapsulation
- CSS Variables: Customize appearance with 100+ CSS variables
- Events vs Callbacks: Events use
on*naming, callbacks use*Callbacksuffix