DataGrid extends KompElement

A virtualized (windowed) grid of records by attributes.

DataGrid renders only the rows currently in the viewport, so memory and layout cost scale with the visible row count rather than the total.

DataGrid requires a bounded height (set height/max-height on the element); it owns its own scroll viewport.

Example

new DataGrid({
    style: 'height: 400px',
    data: records,
    columns: [
        { header: 'Name', width: 200, render: r => r.name, frozen: true },
        { header: 'Team', width: 160, attribute: 'team' }
    ]
})

Constructor


new DataGrid(options)

options :


            
                Object

optional

data :


            
                Array
                |
            
                Promise.<Array>

optional

records (one DataGridRow per record); may be a promise of the array, or an array of per-record promises, in which case a loader can render while it resolves (see loading)

columns :


            
                Array

optional

column configs (DataGridColumn)

rowHeight :


            
                number

optional

estimated height for unmeasured rows

defaultColumnWidth :


            
                number

optional

width for columns without width

overscan :


            
                number

optional

extra rows mounted above/below the viewport

rowClass :


            
                function

optional

(record) => class applied to each row element (string, token array, or State); re-evaluated each time a row mounts

empty :


            
                function

optional

() => content rendered in the body when there are no rows

loading :


            
                function

optional

() => content rendered in the body while data is still resolving (rows not yet built); removed once rows are in place

loadRecords :


            
                function

optional

(records) => Promise batch loader called with the records of rows entering the window (overscan included), before their cells render. Hydrate the records in place (e.g. fetch and merge nested associations) and resolve when done; cells render once the batch settles. Mount-driven only: records accessed while off-screen (e.g. Spreadsheet copy across an off-screen range) are not loaded.

loadingRow :


            
                function

optional

(record, row) => content rendered inside a row while loadRecords is resolving its record; replaced by cells once the load settles

content :


            
                string
                |
            
                HTMLElement
                |
            
                Array
                |
            
                Object

optional

content to append to element. Passed to Dolla's content

Instance Properties


cells

Every cell as a CellHandle (lazy, transient — see plan §1.1).


mountedRows

Row controllers currently in the window.

Static Properties


assignableAttributes: 
            
                Object

Attributes settable via constructor options. Each key is the attribute name and the value is a schema object describing how to handle it.

Example

static assignableAttributes = {
    anchor: { type: 'HTMLElement', default: null, null: true },
    placement: { type: 'string', default: 'bottom', null: false },
    enabled: { type: 'boolean', default: true, null: false },
    data: { type: 'array', default: [], null: false }
}

Properties

type :


            
                string
                |
            
                Array.<string>

expected type(s): 'string', 'number', 'boolean', 'object', 'array', 'function', or a class/element name like 'HTMLElement'

default :

default value when none is provided

null :


            
                boolean

whether null is an acceptable value

load :


            
                function

optional

optional transform applied when reading the attribute value


assignableMethods: 
            
                Array

Methods overridable via constructor options


bindMethods: 
            
                Array

Methods to auto-bind to this


events: 
            
                Array

Event names that can be bound via onEventName constructor options


style: 
            
                string

CSS injected once per component via adoptedStyleSheets


styleLayer: 
            
                string
                |
            
                false

CSS @layer name used to wrap the component's styles when injected via adoptedStyleSheets. Set to a falsy value to disable layering.


watch: 
            
                Array

Attributes to observe for changes. Triggers changed(attribute, was, now) and [attribute]Changed(was, now) callbacks.

Instance Methods


addEventListenerFor(element, eventType, args)

Listen for events on another element, automatically cleaned up when this component disconnects

Parameters

element :


            
                HTMLElement

element to listen on

eventType :


            
                string

event type

args :

additional arguments passed to addEventListener


applyColumnGeometry()

Publish the column tracks + total width as custom properties on the grid. The header and every row inherit --dg-template-columns / --dg-width via CSS, so column geometry has a single update point (call this after any column width/order change) instead of writing the template on each row.


at()

CellHandle at (column, row); negative indices count from the end.


changed(attribute, was, now)

Called every time an observed attribute changes. Attribute must be listed in static watch.

Parameters

attribute :


            
                string

the attribute that changed

was :

previous value

now :

new value


connected()

Called when element is connected to the DOM


disconnected()

Called when element is disconnected from the DOM


initialize()

Called once per instantiation, but only after element is connected to the DOM


queryCells()

Query mounted cells by CSS selector → handles (off-screen cells can't match).


reflow()

Recompute body size + reposition after a height change (from the observer).


remove(callback)
    
    
    
        →
        
            
                
                    KompElement

Remove element. Fires remove, calls optional callback, removes from DOM, then fires removed.

Parameters

callback :


            
                function

optional

async callback called between remove and removed

Returns


                        
                            KompElement

this


renderEmptyState()

Show the empty content in the body when there are no rows; remove it otherwise.


renderLoadingState(active)

Show/hide the loading content in the body.

Called with no argument from DataGrid#updateWindow, it's automatic: the loader shows while data is still resolving (before DataGrid#initializeRows has built this.rows) and is removed once rows are in place. Because rows are initialized last (after the scaffold + first window paint), a grid with async data renders its header and a loader immediately.

The app can also call it directly to override that automatic behavior — e.g. while reloading data, when this.rows still holds the previous payload:

grid.renderLoadingState(true)    // force the loader on before refetching
grid.data = fetchRecords()       // ...reassign data / rebuild rows...
await grid.initializeRows()
grid.renderLoadingState(false)   // force it off (or null → back to automatic)
grid.updateWindow()

Parameters

active :

optional

force on (true) / off (false); null or omitting it restores automatic behavior (shown only until rows resolve). An explicit value persists across the automatic no-arg calls from updateWindow.


slice()

Rectangular range of CellHandles between two handles (row-major).


spliceColumns(index, deleteCount, newConfigs)
    
    
    
        →
        
            
                
                    Array.

<DataGridColumn>

Splice the column set in place (Array#splice semantics over this.columns), then rebuild the dependent structure: column indices, column geometry, the published --dg-* custom properties, and the header. Mounted rows are bound to the previous columns by index, so the window is torn down and rebuilt — recycled cells re-bind to the new column set on the next updateWindow.

Parameters

index :


            
                number

0-based position to start at

deleteCount :


            
                number

optional

columns to remove at index

newConfigs :


            
                Object
                |
            
                DataGridColumn

column configs (or controllers) to insert

Returns


                        
                            Array.<DataGridColumn>

the inserted column controllers


trigger(eventName, args)

Trigger an event on this element

Parameters

eventName :


            
                string

event name to trigger

args :

additional arguments


visibleRange()

Compute the [start, end] row index range to mount, including overscan.

Events


connect

Fired before the element is connected to the DOM (cancellable)


connected

Fired after the element is connected to the DOM and initialized


disconnect

Fired before the element is disconnected from the DOM (cancellable)


disconnected

Fired after the element is disconnected from the DOM


remove

Fired before the element is removed (cancellable)


removed

Fired after the element is removed