<!-- https://svgrid.com/docs/help/web-components/sv-grid/ - SvGrid documentation as markdown. Index of every page: https://svgrid.com/llms.txt -->

# `<sv-grid>` reference

Every property, attribute and event of the custom element.

**This page is generated** from `<SvGrid>`'s own `Props` type by
`packages/grid-wc/scripts/generate-surface.mjs`, and CI fails if it drifts. The
element used to declare 7 props and 2 events by hand while the docs claimed
"grouping, sorting, pagination all come along" - a hand-written table is how
that happens.

## Attributes vs properties

`groupable` is an attribute; `groupBy` is an array, so it is property-only. This grid uses both.

> Live demo: Grouping + aggregation - https://svgrid.com/demos/07-grouping-aggregation/

The distinction matters more here than anywhere else in the API:

- **An attribute is a string.** Primitives (`boolean`, `number`, `string`) can
  be written in HTML: `<sv-grid page-size="25" show-row-numbers>`.
- **Arrays, objects and functions cannot.** `columns='[object Object]'` is not
  a thing. Assign them in script: `el.columns = [...]`.

Both work through the property, so `el.pageSize = 25` is equally valid. The
attribute is the extra convenience, offered only where it can work.

```html
<sv-grid id="grid" sortable filterable page-size="25" row-height="32"></sv-grid>
<script type="module">
  const grid = document.getElementById('grid')
  grid.columns = [{ field: 'name', header: 'Name' }]   // property: an array
  grid.data = rows                                      // property: an array
</script>
```

<!-- BEGIN generated reference - packages/grid-wc/scripts/generate-surface.mjs -->

### Attributes (84)

Primitives, so they work in plain HTML as well as through a property.

| Attribute | Property | Type |
| --- | --- | --- |
| `pivot-mode` | `pivotMode` | `boolean` |
| `context-menu` | `contextMenu` | `boolean \| ReadonlyArray<ContextMenuItem<TData>>` |
| `selection-bar` | `selectionBar` | `\| boolean \| ReadonlyArray<SelectionBarAction<TData> \| SelectionBarBuiltin> \| SelectionB...` |
| `row-adder` | `rowAdder` | `boolean \| RowAdderConfig<TData>` |
| `column-adder` | `columnAdder` | `boolean \| ColumnAdderConfig` |
| `field-menu` | `fieldMenu` | `boolean` |
| `expand-rows` | `expandRows` | `boolean` |
| `pin-splitter` | `pinSplitter` | `boolean` |
| `primary-field` | `primaryField` | `string` |
| `sortable` | `sortable` | `boolean` |
| `filterable` | `filterable` | `boolean` |
| `editable` | `editable` | `boolean` |
| `groupable` | `groupable` | `boolean` |
| `group-footers` | `groupFooters` | `boolean` |
| `grand-total-row` | `grandTotalRow` | `boolean` |
| `group-display-mode` | `groupDisplayMode` | `GroupDisplayType` |
| `auto-group-column-header` | `autoGroupColumnHeader` | `string` |
| `auto-group-column-width` | `autoGroupColumnWidth` | `number` |
| `pageable` | `pageable` | `boolean` |
| `loading` | `loading` | `boolean` |
| `loading-overlay` | `loadingOverlay` | `boolean` |
| `loading-skeleton-rows` | `loadingSkeletonRows` | `number` |
| `error` | `error` | `string \| null` |
| `empty-message` | `emptyMessage` | `string` |
| `show-global-filter` | `showGlobalFilter` | `boolean` |
| `show-column-filters` | `showColumnFilters` | `boolean` |
| `filter-mode` | `filterMode` | `"row" \| "menu" \| "global" \| "none"` |
| `show-grouping-controls` | `showGroupingControls` | `boolean` |
| `show-row-selection` | `showRowSelection` | `boolean` |
| `show-pagination` | `showPagination` | `boolean` |
| `page-size` | `pageSize` | `number` |
| `pagination-position` | `paginationPosition` | `'top' \| 'bottom' \| 'both'` |
| `external-pagination` | `externalPagination` | `boolean` |
| `row-count` | `rowCount` | `number` |
| `page-index` | `pageIndex` | `number` |
| `virtualization` | `virtualization` | `boolean` |
| `row-height` | `rowHeight` | `number \| ((rowIndex: number) => number)` |
| `auto-row-height` | `autoRowHeight` | `boolean` |
| `row-resize` | `rowResize` | `boolean` |
| `header-height` | `headerHeight` | `number` |
| `overscan` | `overscan` | `number` |
| `container-height` | `containerHeight` | `number \| string` |
| `column-virtualization` | `columnVirtualization` | `boolean` |
| `column-overscan` | `columnOverscan` | `number` |
| `column-width` | `columnWidth` | `number` |
| `fit-columns` | `fitColumns` | `boolean` |
| `column-resize` | `columnResize` | `boolean` |
| `responsive` | `responsive` | `boolean \| { breakpoint?: number }` |
| `show-filter-menu` | `showFilterMenu` | `boolean` |
| `show-filter-row` | `showFilterRow` | `boolean` |
| `enable-cell-selection` | `enableCellSelection` | `boolean` |
| `move-cells` | `moveCells` | `boolean` |
| `enable-row-hover` | `enableRowHover` | `boolean` |
| `copy-headers-to-clipboard` | `copyHeadersToClipboard` | `boolean` |
| `enable-inline-editing` | `enableInlineEditing` | `boolean` |
| `edit-on-second-click` | `editOnSecondClick` | `boolean` |
| `full-row-editing` | `fullRowEditing` | `boolean` |
| `enable-row-summaries` | `enableRowSummaries` | `boolean` |
| `summary` | `summary` | `boolean` |
| `status-bar` | `statusBar` | `\| boolean \| { ... }` |
| `tool-panel` | `toolPanel` | `boolean` |
| `charting` | `charting` | `boolean \| ChartingConfig<TData>` |
| `column-menu-tabs` | `columnMenuTabs` | `boolean` |
| `tool-panel-default-open` | `toolPanelDefaultOpen` | `boolean` |
| `tool-panel-default-tab` | `toolPanelDefaultTab` | `"columns" \| "filters"` |
| `selection-mode` | `selectionMode` | `"row" \| "cell" \| "both" \| "none"` |
| `show-row-numbers` | `showRowNumbers` | `boolean` |
| `zebra-rows` | `zebraRows` | `boolean` |
| `row-number-width` | `rowNumberWidth` | `number` |
| `external-sort` | `externalSort` | `boolean` |
| `external-filter` | `externalFilter` | `boolean` |
| `editable-comments` | `editableComments` | `boolean` |
| `conditional-stat-scope` | `conditionalStatScope` | `"filtered" \| "visible" \| "all"` |
| `detail-row-height` | `detailRowHeight` | `number \| ((row: TData) => number)` |
| `show-detail-toggle` | `showDetailToggle` | `boolean` |
| `frozen-rows` | `frozenRows` | `number` |
| `sticky-group-rows` | `stickyGroupRows` | `boolean` |
| `row-layout` | `rowLayout` | `"flex" \| "table"` |
| `enable-column-reorder` | `enableColumnReorder` | `boolean` |
| `infer-column-types` | `inferColumnTypes` | `boolean` |
| `row-drag-managed` | `rowDragManaged` | `boolean` |
| `row-drag-group` | `rowDragGroup` | `string` |
| `aligned-grid-group` | `alignedGridGroup` | `string` |
| `filter-locale` | `filterLocale` | `string \| ReadonlyArray<string>` |

### Properties only (40)

Arrays, objects and functions. An HTML attribute is a string, so these can
only be assigned in script: `el.columns = [...]`.

| Property | Type |
| --- | --- |
| `data` | `ReadonlyArray<TData>` |
| `columns` | `Array<ColumnDef<TFeatures, TData>>` |
| `board` | `BoardConfig<TFeatures, TData>` |
| `gallery` | `GalleryConfig<TFeatures, TData>` |
| `scheduler` | `SchedulerConfig<TFeatures, TData>` |
| `gantt` | `GanttConfig<TFeatures, TData>` |
| `chart` | `ChartViewConfig<TFeatures, TData>` |
| `pivot` | `GridPivotConfig<TData>` |
| `rowColor` | `RowColorConfig<TData>` |
| `features` | `TFeatures` |
| `treeData` | `{ ... }` |
| `groupBy` | `ReadonlyArray<string>` |
| `expanded` | `Record<string, boolean>` |
| `localization` | `GridLocalization` |
| `pageSizeOptions` | `number[]` |
| `initialColumnPinning` | `{ ... }` |
| `processCellForFill` | `(params: { value: unknown; delta: { rows: number; cols: number }; rowIndex: number; col...` |
| `processCellForClipboard` | `(params: { ... }) => unknown` |
| `includeCollapsedRows` | `(rowIndex: number) => boolean` |
| `clipboardHtml` | `(params: { rects: ReadonlyArray<{ ... }>; text: string; }) => string \| null \| undefined` |
| `processCellFromClipboard` | `(params: { ... }) => unknown` |
| `initialSorting` | `Array<{ id: string; desc: boolean }>` |
| `initialAdvancedFilter` | `GridPredicateExpr \| null` |
| `getRowId` | `(row: TData, index: number) => string` |
| `rowClass` | `(ctx: { row: TData; rowIndex: number; }) => string \| ReadonlyArray<string> \| Record<str...` |
| `notes` | `Record<string, Record<string, string>>` |
| `conditionalFormats` | `ReadonlyArray<ConditionalFormat<TData>>` |
| `rowPlaceholder` | `(row: TData, rowIndex: number) => "loading" \| "failed" \| null` |
| `rowModel` | `GridRowModel<TData>` |
| `pivotResultColumns` | `Array<ColumnDef<TFeatures, TData>> \| null` |
| `rowSelectionModel` | `{ ... }` |
| `isDetailRow` | `(row: TData, rowIndex: number) => boolean` |
| `isDetailOpen` | `(row: TData) => boolean` |
| `hasDetail` | `(row: TData) => boolean` |
| `serverGroup` | `{ ... }` |
| `serverFilterValues` | `(columnId: string) => Promise<string[]>` |
| `pinnedTopRows` | `ReadonlyArray<TData>` |
| `mergedCells` | `ReadonlyArray<{ ... }>` |
| `pinnedBottomRows` | `ReadonlyArray<TData>` |
| `columnOrder` | `ReadonlyArray<string>` |

### Events (32)

`detail` is the callback's argument. The one callback that takes two carries
an object keyed by its parameter names.

| Event | From | `detail` |
| --- | --- | --- |
| `pivotmodechange` | `onPivotModeChange` | `on` |
| `rowadd` | `onRowAdd` | `event` |
| `columnadd` | `onColumnAdd` | `event` |
| `columnchange` | `onColumnChange` | `event` |
| `columnremove` | `onColumnRemove` | `event` |
| `rowsdelete` | `onRowsDelete` | `event` |
| `rowcolorchange` | `onRowColorChange` | `config` |
| `expandedchange` | `onExpandedChange` | `expanded` |
| `paginationchange` | `onPaginationChange` | `pagination` |
| `columnresize` | `onColumnResize` | `event` |
| `rowresize` | `onRowResize` | `event` |
| `pasteclipboard` | `onPasteClipboard` | `payload` |
| `apiready` | `onApiReady` | `api` |
| `rowselectionchange` | `onRowSelectionChange` | `{ selection, rows }` |
| `cellselectionchange` | `onCellSelectionChange` | `ranges` |
| `sortingchange` | `onSortingChange` | `sorting` |
| `advancedfilterchange` | `onAdvancedFilterChange` | `expr` |
| `filterschange` | `onFiltersChange` | `filters` |
| `notechange` | `onNoteChange` | `event` |
| `cellvaluechange` | `onCellValueChange` | `event` |
| `activecellchange` | `onActiveCellChange` | `cell` |
| `cellclick` | `onCellClick` | `event` |
| `rowclick` | `onRowClick` | `row` - published detail is the row, not the whole click event |
| `celldoubleclick` | `onCellDoubleClick` | `event` |
| `rowdoubleclick` | `onRowDoubleClick` | `event` |
| `scrollbottomreached` | `onScrollBottomReached` | `event` |
| `visiblerangechange` | `onVisibleRangeChange` | `range` |
| `retryrow` | `onRetryRow` | `{ row, rowIndex }` |
| `detailtoggle` | `onDetailToggle` | `{ row, rowIndex }` |
| `columnorderchange` | `onColumnOrderChange` | `order` |
| `rowdragend` | `onRowDragEnd` | `event` |
| `rowdrop` | `onRowDrop` | `event` |

Plus one alias kept from before the surface was generated:

| Event | From | `detail` |
| --- | --- | --- |
| `selectionchange` | `onRowSelectionChange` | `rows` - published alias of rowselectionchange, detail is the selected rows |

### Not exposed (3)

| Prop | Why |
| --- | --- |
| `selectable` | element-level shorthand for row selection - see GridBody.svelte |
| `icons` | Svelte snippets keyed by icon name - cannot cross the custom-element boundary |
| `renderDetailRow` | Svelte snippet - cannot cross the custom-element boundary |

<!-- END generated reference -->

## The imperative API

The api surface `apiready` hands you.

> Live demo: Selection API + events - https://svgrid.com/demos/90-selection-api/

`onApiReady` fires once with the grid's api. Because a listener bound after
mount would miss it, the handle is also parked on the element:

```js
grid.addEventListener('apiready', (e) => e.detail.exportCsv())
// or, at any time later:
grid.api.exportCsv()
```

## See also

- [Quick start](https://svgrid.com/docs/help/web-components/quick-start/) - the CDN path, no build step.
- [Limitations](https://svgrid.com/docs/help/web-components/limitations/) - what cannot cross the boundary.
- [Shadow DOM](https://svgrid.com/docs/help/web-components/shadow-dom/) - `<sv-grid-shadow>` and style isolation.

---

SvGrid is the Svelte 5 data grid (`npm install @svgrid/grid`, MIT). This page: https://svgrid.com/docs/help/web-components/sv-grid/ . All docs: https://svgrid.com/llms.txt