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

optional

records; one DataGridRow per record

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

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


slice()

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


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