Grid

import "@taprootio/espalier/grid";

Default

Grid has a default slot that expects <esp-grid-column> elements to define the columns in the grid:

The grid also supports cursor-based infinite scrolling. Instead of fetching all data up front, provide a fetchPage callback that returns a page of items and a cursor for the next page. The grid virtualizes the rows and fetches more data as the user scrolls. Search and sort are delegated to the server via the callback parameters. > Warning: Every column in an infinite-scroll grid must have an > explicit width attribute. Use the grow attribute on one or more > columns to fill remaining horizontal space when the grid is wider > than its content.

When the total number of items is smaller than the configured grid-height, the grid automatically shrinks to fit after data loads. This also works after sort, search, and reload — the grid re-measures and adjusts its height each time.

The grid also regrows when a reload returns more items. In this example the grid starts with 1 row (compact), then clicking "Load more" replaces the data with 10 rows and the grid expands to fit.

Columns can use a .template callback to render custom web components inside each cell. The grid explicitly waits for Lit-based custom elements (those exposing updateComplete) to finish rendering before measuring row heights. For other custom elements, a zero-height guard prevents the grid from collapsing if the element hasn't painted yet. In the example below, a <grid-cell-demo> custom element renders a two-line contact cell with the person's name and email.

header-buttons

The header buttons slot is for adding buttons next to the search box at the top of the grid. Useful for things like an add item button:

data-field

data-field has a default value of "".

If there is a data-url specified, the name of the field on the response to get the array of items from. If it is empty, the API response should simply return an array of data items.

data-url

data-url has a default value of "".

Specify a URL the grid will fetch data from.

items

items has a default value of undefined.

If using a data-url, the items retrieved are available in the items property. An items array can be assigned instead of using a data-url.

Assigning a new items array preserves the grid's current intrinsic state: an active search term is re-applied to the new items, the active sort column re-sorts them, and the current page is kept when it still exists (clamping to the nearest valid page otherwise). Infinite grids delegate search and sort to the server through fetchPage instead.

page-size

page-size has a default value of 10.

The number of items to display on a page. In paged mode this controls how many rows are shown per page. In infinite scroll mode this controls how many items are fetched per request.

grid-height

grid-height has a default value of "60vh".

The height of the grid when in infinite scroll mode. Accepts any valid CSS height value. Defaults to 60vh.

If the loaded content is shorter than this value (and there are no more pages to fetch), the grid shrinks to fit.

search-fields

search-fields has a default value of [].

The fields to include when filtering results. It defaults to an empty array, which includes all fields. The test dataset includes an address field that is not displayed, so to only filter results by fields displayed in the grid, specify those fields in the search-fields attribute.

Warning: When specifying arrays in plain HTML, the attributes should be wrapped in single quotes.

intent

intent has a default value of undefined.

The element's intent — its meaning: neutral (no pin), or success, warning, danger, info — each pinned to its fixed status family (blue for info), retunable per theme via intents. On token-emitting controls a non-neutral intent pins the filled-action pair to that family, derived over the governing zone's theme; class-styled chrome (badges, callouts, status pills) opts out of inline emission and renders its treatment from CSS classes instead. An intent never repaints the surrounding zone, which is what contexts are for. Removing the attribute restores the element's own default intent.

context

context has a default value of undefined.

A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.

delete

Deletes items from the grid where the lookup function returns true.

addOrReplace

Adds or replaces the item from the grid where the lookup function returns true. If there is more than one match, only the first match is replaced.

addInOrder

Inserts or replaces an item in sorted order. If an existing item matches the lookup function, it is replaced in-place. Otherwise the new item is inserted at the position determined by the compare function (same semantics as Array.prototype.sort).

Returns the index of the inserted or replaced item, which can be passed to scrollToIndex to scroll the item into view.

scrollToIndex

Scrolls to the item at the given index.

In infinite mode this waits for the virtualizer to complete its layout pass, then delegates to its scrollToIndex method.

In paged mode this navigates to the page containing the item at index.

clear

Clears all items from the grid.

reload

Clears all loaded data and re-fetches from the beginning.

In infinite mode this resets the cursor and triggers a fresh fetchPage call. In paged mode this is a no-op (use the data-url attribute to reload).

traverseToClosest

Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.

esp-grid-event

esp-grid-event is of type CustomEvent<GridClickedEvent>.

The grid listens for click events, and if a child element has a grid-event attribute, grid publishes an event with the grid, clicked element, and associated data.

esp-grid-load-start

esp-grid-load-start is of type CustomEvent<GridLoadStartEventDetail>.

Fired before the grid starts fetching a page of data.

esp-grid-load-success

esp-grid-load-success is of type CustomEvent<GridLoadSuccessEventDetail>.

Fired after fetched items have been applied to the grid.

esp-grid-load-error

esp-grid-load-error is of type CustomEvent<GridLoadErrorEventDetail>.

Fired when a grid data fetch fails.

esp-grid-items-changed

esp-grid-items-changed is of type CustomEvent<GridItemsChangedEventDetail>.

Fired whenever the grid's current item set changes.

--esp-grid-border-outer

Border style of the grid's outer edge. Defaults to 2px solid var(--esp-color-border).

--esp-grid-border-inner

Border style of the grid's internal section separators. Defaults to 2px solid var(--esp-color-border).

--esp-grid-background

Background color of the grid container. Defaults to var(--esp-color-layer-1).

--esp-grid-text-color

Text color used by the grid. Defaults to var(--esp-color-text).

--esp-grid-header-background

Background color of header rows and pinned header cells. Defaults to var(--esp-color-layer-4).

--esp-grid-header-active-background

Background color used for sorted or hovered sortable headers. Defaults to var(--esp-color-layer-3).

--esp-grid-row-background-odd

Background color of odd rows. Defaults to var(--esp-color-layer-1).

--esp-grid-row-background-even

Background color of even rows. Defaults to var(--esp-color-layer-2).

--esp-grid-row-hover-background

Background color of hovered rows. Defaults to var(--esp-color-layer-3).

--esp-grid-cell-border-color

Cell divider color used throughout the grid. Defaults to var(--esp-color-layer-3).

--esp-grid-row-hover-border-color

Divider color used while rows are hovered. Defaults to var(--esp-color-layer-4).

--esp-grid-link-color

Link color used inside grid cells. Defaults to var(--esp-color-link).

--esp-grid-link-hover-color

Link hover decoration color used inside grid cells. Defaults to var(--esp-color-link-hover).

--esp-field-background

Background color of the shared field shell. Defaults to var(--esp-color-layer-2).

--esp-field-border-color

Border color of the shared field shell. Defaults to var(--esp-color-border).

--esp-field-border-width

Border width of the shared field shell. Defaults to 1px.

--esp-field-text-color

Text color used inside the shared field shell. Defaults to var(--esp-color-text).

--esp-field-hover-bg

Hover background color of the shared field shell. Derived from --esp-field-background.

--esp-field-focus-bg

Focus background color of the shared field shell. Derived from --esp-field-background.

--esp-field-focus-shadow

Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).