Tree List API

Complete API reference for @oge-ui/tree-list. Columns, templates and configuration are shared with the grid — see the Data Grid API for <oge-column> and the option objects; this page documents the tree surface and the differences.

Properties Methods Events Types

OgeTreeList

oge-tree-list

Properties 33

Tree data

Name	Type	Default	Description
`data`	`readonly T[] \| DataSource<T>`	`[]`	Flat self-referencing rows: a static array or any DataSource.
`keyExpr`	`string \| ((row: T) => RowKey)`	`'id'`	Row key: field path or selector (grid uses `keyField`).
`parentIdExpr`	`string \| ((row: T) => unknown)`	`'parentId'`	Parent reference: field path or selector.
`rootValue`	`unknown`	`null`	Parent value marking root rows.
`orphanPolicy`	`'discard' \| 'promoteToRoot'`	`'discard'`	Rows whose parent key is missing: drop or render as roots.
`itemsExpr`	`string \| ((row: T) => readonly T[] \| undefined) \| undefined`	—	Nested payloads: rows carry children inline (plain arrays only; `parentIdExpr` ignored).
`hasItemsExpr`	`string \| ((row: T) => boolean) \| undefined`	—	Expandability hint for lazily loaded children.
`loadMode`	`'full' \| 'lazy' \| undefined`	—	`'lazy'` fetches children per expansion (`filter: [parentIdExpr,'=',key]`); defaults to lazy with DataSource + `hasItemsExpr`.

Expansion & focus

Name	Type	Default	Description
`autoExpandAll`	`boolean`	`false`	Expands every row initially; the toggled-set polarity follows.
`expandedRowKeys`	`model<readonly RowKey[]>`	`[]`	Two-way binding of the expanded row keys.
`expandNodesOnFiltering`	`boolean`	`true`	Auto-expands ancestor chains of matches while a filter is active.
`focusedRowEnabled`	`boolean`	`false`	Highlights and tracks a single focused row.
`focusedRowKey`	`model<RowKey \| null>`	`null`	Two-way binding of the focused row's key.
`autoNavigateToFocusedRow`	`boolean`	`false`	A `focusedRowKey` change expands its ancestor path and scrolls (tree-only).

Selection

Name	Type	Default	Description
`selectionMode`	`OgeSelectionMode`	`'none'`	none \| single \| multiple \| checkbox.
`selectedKeys`	`model<RowKey[]>`	`[]`	Two-way binding of the selected row keys.
`selectionRecursive`	`boolean`	`false`	Tri-state cascade to descendants and ancestors.
`allowSelectAll`	`boolean`	`true`	Hides the header select-all checkbox when false.

Filtering & paging

Name	Type	Default	Description
`filterRow / headerFilter / searchPanel / filterPanel`	`boolean \| options`	`false`	Same options objects as the grid — all client-side over the loaded rows.
`filterMode`	`TreeFilterMode`	`'withAncestors'`	Matches keep their ancestors; `'fullBranch'` also keeps all descendants.
`filterValue`	`model<FilterExpr \| null>`	`null`	Two-way filter expression (builder).
`filterDebounce`	`number \| undefined`	—	Debounce for text filter inputs.
`announcements`	`boolean \| undefined`	`config.announcements (true)`	Speaks sort, filter/search result count (debounced, once the new result arrived), page, row expansion, select-all and blocked-save validation changes through the shared `OgeLiveAnnouncer` regions — texts from the `*Announcement` messages. `false` opts out.
`paging`	`false \| OgePagingOptions`	`false`	Pages the visible (flattened) rows client-side; paging wins over `virtualScroll`.
`summary`	`OgeTreeListSummary<T> \| undefined`	—	Aggregates (`sum` / `avg` / `min` / `max` / `count` / `custom`). `totalItems` render in a footer row over every row the filter leaves visible, at every level (collapsed branches included); `recursiveItems` show each parent its visible descendants’ aggregate beside its own value. Both are part of the Excel / PDF exports (total row, per-parent footer lines).
`remoteOperations`	`OgeTreeListRemoteOperations \| undefined`	—	`{ filtering: true }` (full load mode) sends the filter row, header filter, builder filter and search text to the data source and asks `source.distinct(field, { filter })` for header-filter values. Server contract: answer with every matching row plus all of its ancestors, flat, in the unfiltered shape; the tree renders the answer as-is (no client re-filtering) and opens the branches leading to the matches. Lazy trees keep their own remote match discovery.
`sortable / sorting`	`boolean \| 'single' \| 'multi' / OgeSortingOptions`	`true`	Sibling-scoped, multi-column by default.

Layout, editing & misc (grid-shared)

Name	Type	Default	Description
`columns`	`readonly (string \| OgeColumnDef<T>)[] \| undefined`	—	Programmatic columns — the grid’s `OgeColumnDef` with every `<oge-column>` option; used when no declarative columns exist (and the way to share columns through a wrapper component).
`virtualScroll / columnRenderingMode / rowHeight / overscan / columnMinWidth`	`various`	—	Virtualization knobs; `columnRenderingMode` is a top-level input here.
`columnHidingMode`	`'hide' \| 'detail' \| undefined`	`config: 'detail'`	What happens to columns responsive hiding (`hidingPriority`) takes out on a narrow grid: `'detail'` gives every row a toggle (a real button with `aria-expanded` / `aria-controls`, labelled by `toggleAdaptiveDetail`) that reveals the hidden columns' caption / value pairs on a second line of the row, rendered like the cells — format, lookups, boolean words and cell templates; `'hide'` drops them with no way back. The hiding pass counts the toggle's 32px track once a column is hidden.
`columnResize / columnReorder / columnChooser`	`boolean`	—	Column UX (defaults: true/true/false), with the grid’s keyboard paths: `Alt+←/→` resizes the focused header’s column (10px, `Shift` 1px) and its handle is a focusable `role="separator"`; `Ctrl+Shift+←/→` moves it; `Ctrl+↑/↓` moves a column-chooser item. Columns take the grid’s `maxWidth`.
`editing`	`false \| OgeEditingOptions`	`false`	cell/row/batch/form/popup via the shared EditingModel.
`commandButtons / rowDragging / rowAlternation / wordWrap / loadPanel / rtlEnabled / messages / stateKey`	`various`	—	Same semantics as the grid; `messages` is the grid’s `OgeGridMessages` catalog — the reparenting handle reads `reparentColumnHeader` / `reparentRow`, boolean cells announce `booleanTrueLabel` / `booleanFalseLabel`. `rowDragging` keyboard: `Ctrl+↑/↓` on a focused cell moves the row among its siblings, `Ctrl+→` indents it under the previous sibling, `Ctrl+←` outdents it after its parent (logical in RTL) — the same drop path and reparent event as a handle drag, announced via `messages.treeRowMoved`.

Methods 19

Tree navigation & data

Name	Type	Description
`expandAll() / collapseAll()`	`void`	Polarity-aware over the expandable keys.
`expandRow(key) / collapseRow(key) / isRowExpanded(key)`	`void / boolean`	Per-row expansion (imperative API bypasses the cancelable events).
`focusRow(key) / navigateToRow(key)`	`void`	Expands the ancestor path, scrolls to the row and focuses its first cell.
`scrollToRow(target: number \| RowKey)`	`void`	Scrolls a visible row into the viewport.
`getNodeByKey(key): T \| undefined`	`T \| undefined`	The loaded row carrying `key`.
`forEachNode(callback)`	`void`	Runs the callback for every loaded row with `(row, key, parentKey)`.
`getVisibleRows(): readonly T[]`	`readonly T[]`	Data rows of the rendered page, in display order.
`refresh(): void`	`void`	Re-runs the load and drops lazily fetched rows.

Selection

Name	Type	Description
`getSelectedRowKeys(mode = 'all')`	`RowKey[]`	`'all' \| 'leavesOnly' \| 'excludeRecursive'` narrows recursive selections.
`getSelectedRowsData(mode = 'all')`	`T[]`	Row data per the same modes.
`selectAll() / deselectAll() / clearSelection() / isRowSelected(key)`	`void / boolean`	Recursive mode cascades select-all to descendants.
`copyToClipboard(): Promise<void>`	`Promise<void>`	Selected rows as tab-separated values (with header).

Editing, paging, state & export

Name	Type	Description
`addRow(parentKey?)`	`void`	New unsaved row; parent pre-staged with a string `parentIdExpr`; `initNewRow` can prefill.
`editRow(key) / deleteRow(key) / saveChanges() / discardChanges() / hasChanges()`	`void / boolean`	Same semantics as the grid.
`pageIndex / setPageIndex(i) / pageSize() / setPageSize(n) / pageCount() / totalCount()`	`signal / methods`	`pageIndex` is a writable signal; `totalCount()` spans all pages.
`beginCustomLoading(message?) / endCustomLoading()`	`void`	Load panel independent of data activity.
`state() / applyState(snapshot)`	`TreeListStateSnapshot / void`	Sort, filters, column layout and expansion. `applyState` validates the snapshot first (`sanitize*StateSnapshot`): unknown keys are dropped, prototype keys rejected, wrong types skipped — invalid input is ignored, never thrown.
`clearFilters() / clearSorting()`	`void`	Reset the view.
`getExportData(options?) / getCsv() / exportCsv()`	`sync`	Synchronous (grid: async). `getExportData` takes `OgeTreeExportOptions` (`visibleColumnsOnly`, `selectedRowsOnly`, `summaries`) and returns rows, levels and the summary lines; CSV indents the first column 2 spaces per level; the Excel entry sets real outline levels. Cells a spreadsheet would evaluate as a formula are apostrophe-prefixed (CSV formula injection); `formulaGuard: false` opts out.

Events 10

Tree-specific

Name	Type	Description
`rowExpanding / rowCollapsing`	`OgeTreeRowTogglingEvent<T>`	Cancelable — UI-driven toggles only (the imperative API stays silent).
`rowExpanded / rowCollapsed`	`OgeTreeRowToggleEvent<T>`	`{ key, row }` after a toggle.
`rowReparented`	`OgeTreeRowReparentEvent<T>`	Drag & drop: `{ key, row, fromParentKey, toParentKey, position: 'inside' \| 'before' \| 'after' }`.
`initNewRow`	`OgeTreeInitNewRowEvent`	`{ key, parentKey, values }` prefill hook.

Shared with the grid

Name	Type	Description
`rowClick / rowDblClick / cellClick / cellDblClick`	`OgeRowClickEvent / OgeCellClickEvent`	Flat payloads with the originating DOM event.
`rowContextMenu / headerContextMenu`	`context-menu events`	Mutable `items`; also opened by the Menu key / Shift+F10 on a focused cell or header (`source: 'keyboard'`, anchored at the cell).
`selectionChanged / focusedRowChanged`	`diff / focus events`	Same payloads as the grid.
`editingStart / rowInserting / rowInserted / rowUpdating / rowUpdated / rowRemoving / rowRemoved / savingChanges / savedChanges / editCanceled`	`editing lifecycle`	Same shared EditingModel pipeline as the grid; `-ing` events cancelable.
`expandedRowKeysChange / selectedKeysChange / focusedRowKeyChange / filterValueChange`	`model change events`	The change halves of the `[(expandedRowKeys)]`, `[(selectedKeys)]`, `[(focusedRowKey)]` and `[(filterValue)]` two-way bindings.
`exporting / dataErrorOccurred / contentReady / stateChange`	`misc`	Same semantics as the grid (`stateChange` carries a `TreeListStateSnapshot`).

Types 10

Name	Type	Description
`OgeTreeDropPosition`	`'inside' \| 'before' \| 'after'`	Reparent vs sibling ordering.
`OgeTreeExportData<T>`	`OgeExportData<T> & { levels: readonly number[] }`	Zero-based depth per exported row (drives spreadsheet outline levels).
`TreeFilterMode`	`'withAncestors' \| 'fullBranch'`	Visible set under a filter.
`exportOgeTreeListToExcel(treeList, options?)`	`@oge-ui/tree-list/export-excel`	Lazy Excel export with native outline grouping, the total row and per-parent summary rows (values or `SUBTOTAL` formulas), grid widths, freeze panes and the grid exporters’ styles.
`OgeTreeListSummary<T> / OgeTreeSummaryItem`	`{ totalItems?; recursiveItems?; calculateCustomSummary? } / { field; type; name?; showInColumn? }`	The `summary` input: items aggregate `field` with a `SummaryType`; `custom` runs `calculateCustomSummary[name ?? field](rows, field)`; `showInColumn` moves the value under another column.
`OgeTreeListRemoteOperations`	`{ filtering?: boolean }`	What the tree hands to its data source (see `remoteOperations` for the server contract).
`OgeTreeExportOptions`	`{ visibleColumnsOnly?; selectedRowsOnly?; summaries? }`	What `getExportData()` and both export entries include.
`exportOgeTreeListToPdf(treeList, options?)`	`@oge-ui/tree-list/export-pdf`	Lazy PDF export (optional `jspdf` + `jspdf-autotable` peers): hierarchy as first-column indentation, the header repeated on every page, total and per-parent summary rows, grid widths fitted to the page, `title`, `pageHeader` / `pageFooter`, `pageNumbers`. `buildTreePdfDocument(data, options)` for custom pipelines. Text outside WinAnsi (Turkish `ğ ş ı İ`, Central European, Greek, Cyrillic) needs a Unicode TrueType `font` — per export, or once for every PDF via `setOgePdfDefaultFont({ family, normal, bold })` from `@oge-ui/behavior`; without one the built-in Helvetica cannot draw it (a dev-mode warning says so).
`OgeTreeExcelExportOptions<T> / OgeTreePdfExportOptions<T>`	`interfaces`	The tree download helpers’ options — the grid exporters’ options (styles, formats, freeze panes, `summaryFormulas`, page chrome) minus grouping.
`Re-exports`	`from @oge-ui/grid`	`OgeColumn`, templates, config/messages and the shared event payload types are re-exported so tree-only consumers have a single import source.

Notes

Key differences from the grid: keyExpr instead of keyField, synchronous export methods, no grouping/master detail, and the extra tree inputs/events documented above.
expandRow()/collapseRow() are polarity-aware under autoExpandAll and do not fire the cancelable rowExpanding/rowCollapsing events — those veto UI-driven toggles only.