List View API

Full surface of oge-list-view: its inputs and models, methods, outputs, the four structural template slots and the config provider.

Properties Methods Events Types

OgeListView

oge-list-view

Properties 21

Data

Name	Type	Default	Description
`items`	`readonly T[]`	`[]`	The items, in order. The component is generic: `T` is inferred from the binding, so templates and event payloads are typed.
`keyExpr`	`string \| ((item: T) => unknown)`	`'id'`	Field (or function) giving each item’s key — the identity in `selectedKeys` and every event. Primitive items are their own key.
`displayExpr`	`string \| ((item: T) => unknown) \| undefined`	—	Field (or function) giving the text of the default row, the search and type-ahead.
`disabledExpr`	`string \| ((item: T) => unknown) \| undefined`	—	Field (or function) marking an item disabled: it stays visible with `aria-disabled`, the keyboard skips it and it never selects.
`groupExpr`	`string \| ((item: T) => unknown) \| undefined`	—	Field (or function) grouping the items (first-appearance order) under sticky headers. Each group is a labelled segment: `role="group"` with `aria-label` in a listbox, a `listitem` holding a labelled nested `list` otherwise; the visible header is `aria-hidden`.

Selection

Name	Type	Default	Description
`selectionMode`	`'none' \| 'single' \| 'multiple'`	`config ?? 'none'`	`none` renders a `role="list"` with a roving tab stop; `single` / `multiple` an APG listbox whose viewport tracks the active option with `aria-activedescendant` (`aria-multiselectable` for multiple).
`selectedKeys`	`readonly OgeListViewKey[] (model)`	`[]`	Keys of the selected items — two-way. Space toggles, Enter selects (single), Shift+arrows / Shift+Space / Shift+click extend a range, Ctrl+Shift+Home/End select to an edge, Ctrl+A selects all (or none).
`showSelectionControls`	`boolean \| undefined`	`config ?? false`	Draws an `aria-hidden` check (multiple) or radio (single) glyph in every row; the state itself is `aria-selected`.
`disabled`	`boolean`	`false`	Disables the whole list: nothing selects or activates, the search field is disabled, the viewport leaves the Tab order.

Scrolling & paging

Name	Type	Default	Description
`height`	`number \| string \| undefined`	—	Height of the scroll viewport — a number is px, a string any CSS length. A virtualized list without one uses 320px.
`virtualScroll`	`boolean \| OgeListViewVirtualScrollOptions`	`false`	Windowed rendering with fixed row heights (`{ itemHeight: 44, groupHeaderHeight: 32, overscan: 6 }`) on core’s offset tree. Keyboard navigation scrolls the active option into the window first; the header of a group the window starts inside stays pinned.
`pageLoadMode`	`'none' \| 'button' \| 'scroll'`	`config ?? 'none'`	`button` renders a Load more button under the list, `scroll` emits `loadMoreRequested` when the viewport nears the end (once per page — also when a first page does not fill the viewport). The arrival of the next items is announced politely.
`hasMore`	`boolean`	`false`	Whether more items can be requested; nothing is requested without it.
`loading`	`boolean`	`false`	Shows the loading row under the list, sets `aria-busy` and holds further requests.

Search, actions & labels

Name	Type	Default	Description
`searchEnabled`	`boolean`	`false`	Renders a labelled search field (with a clear button) above the list; ArrowDown moves into the list, Escape clears. Matching is locale- and accent-insensitive and the result count is announced.
`searchExpr`	`OgeListViewSearchExpr<T> \| undefined`	—	Field(s) the search matches — one expression or an array; default the display text.
`searchMode`	`'contains' \| 'startsWith'`	`config ?? 'contains'`	How the search text matches.
`searchValue`	`string (model)`	`''`	The search text — two-way.
`itemActions`	`readonly OgeListViewItemAction[]`	`[]`	Per-item actions, revealed by a horizontal swipe on touch (mirrored in RTL) and on hover / focus with a mouse. They are `aria-hidden` glyphs inside the row (an option cannot hold buttons); the keyboard twin is each action’s `shortcut`, listed in `aria-keyshortcuts` and in a shared description.
`ariaLabel`	`string \| undefined`	`messages.listLabel`	Accessible name of the list / listbox.
`locale`	`string \| undefined`	`config ?? LOCALE_ID`	BCP 47 locale of the announced counts (ICU plurals).

Methods 5

Name	Type	Description
`focus()`	`() => void`	Moves focus into the list — the listbox viewport, or the active item of a plain list — and scrolls the active item into view.
`scrollToItem(key)`	`(key: OgeListViewKey) => void`	Scrolls the item with `key` into view and makes it the active one.
`clearSelection()`	`() => void`	Clears the selection (emits `selectionChanged`).
`selectAll()`	`() => void`	Selects every enabled item of a multiple-selection list and announces the count.
`clearSearch()`	`() => void`	Empties the search field.

Events 7

Name	Type	Description
`selectedKeysChange`	`readonly OgeListViewKey[]`	The banana half of `[(selectedKeys)]`.
`searchValueChange`	`string`	The banana half of `[(searchValue)]`.
`selectionChanged`	`OgeListViewSelectionChangedEvent<T>`	The selection changed through a click, a key, a range, Ctrl+A or a method — with the previous, added and removed keys, the item and the originating event.
`itemClick`	`OgeListViewItemClickEvent<T>`	An item was clicked or activated with Enter.
`itemActionClick`	`OgeListViewItemActionClickEvent<T>`	An item action ran — by tap, click or its keyboard shortcut (one event for all three).
`loadMoreRequested`	`OgeListViewLoadMoreEvent`	The list asks for more items: `reason` `button` or `scroll`, and the `itemCount` held now (the next page’s offset).
`activeItemChanged`	`OgeListViewActiveItemChangedEvent<T>`	The active (keyboard) item moved.

Types 15

Template slots

Name	Type	Description
`OgeListViewItemTemplate`	`[ogeListViewItemTemplate]`	Replaces each row’s content. Context `OgeListViewItemTemplateContext`: `$implicit` item, `index`, `key`, `selected`, `active`, `disabled`, `group`. Keep it non-interactive — an option cannot hold controls.
`OgeListViewGroupTemplate`	`[ogeListViewGroupTemplate]`	Replaces each sticky header’s text. Context `OgeListViewGroupTemplateContext`: `$implicit` group label, `count`.
`OgeListViewEmptyTemplate`	`[ogeListViewEmptyTemplate]`	Replaces the empty state. Context `OgeListViewEmptyTemplateContext`: `$implicit` searching, `searchValue`.
`OgeListViewFooterTemplate`	`[ogeListViewFooterTemplate]`	Content under the list; replaces the Load more button. Context `OgeListViewFooterTemplateContext`: `$implicit` loadMore function, `loading`, `hasMore`, `itemCount`.

Vocabulary

Name	Type	Description
`OgeListViewKey`	`string \| number`	Identity of an item.
`OgeListViewExpr / OgeListViewSearchExpr`	`string \| ((item: T) => unknown) / one or an array`	Field names or reader functions.
`OgeListViewSelectionMode`	`'none' \| 'single' \| 'multiple'`	Selection union.
`OgeListViewPageLoadMode / OgeListViewSearchMode`	`'none' \| 'button' \| 'scroll' / 'contains' \| 'startsWith'`	Paging and search unions.
`OgeListViewItemAction`	`{ key; label; icon?; severity?: 'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'; shortcut? }`	A swipe / hover action; `icon` is SVG path data, `shortcut` an `aria-keyshortcuts` value (`Delete`, `Shift+A`).
`OgeListViewVirtualScrollOptions`	`{ itemHeight?; groupHeaderHeight?; overscan? }`	Options form of `virtualScroll`.
`OgeListViewSelectionChangedEvent`	`{ selectedKeys; previousKeys; addedKeys; removedKeys; item?; event? }`	Payload of `selectionChanged`.
`OgeListViewItemClickEvent / OgeListViewActiveItemChangedEvent`	`{ item; key; index; event? }`	Payloads of `itemClick` / `activeItemChanged`.
`OgeListViewItemActionClickEvent`	`{ action; item; key; index; event? }`	Payload of `itemActionClick`.
`OgeListViewLoadMoreEvent`	`{ reason: 'button' \| 'scroll'; itemCount }`	Payload of `loadMoreRequested`.
`OgeListViewActionSeverity`	`'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'`	Colour of an action.

Configuration

Properties 2

Name	Type	Description
`provideOgeListViewConfig(config)`	`(config: OgeListViewConfigInput \| (() => OgeListViewConfigInput)) => Provider`	Application- or component-scoped defaults for `selectionMode`, `searchMode`, `showSelectionControls`, `pageLoadMode`, `locale` and the `messages` (a function makes it live). Translated in every `@oge-ui/locales` pack (`layout.listView`).
`OGE_LIST_VIEW_CONFIG`	`InjectionToken<OgeListViewConfig>`	The token behind `provideOgeListViewConfig()`, with `OGE_DEFAULT_LIST_VIEW_CONFIG` as its factory default.

Types 2

Name	Type	Description
`OgeListViewMessages`	`interface`	Every user-facing string: `listLabel`, `searchLabel`, `searchPlaceholder`, `clearSearch`, `loadMore`, `loading`, `noData`, `noResults`, the ICU plurals `resultsCount` / `loadedCount` / `selectedCount` over `{count}`, and `itemActions` (`{actions}`). `OGE_DEFAULT_LIST_VIEW_MESSAGES` is the English catalog.
`OgeListViewConfig / OgeListViewConfigInput`	`interface`	The config shape and its partial input; `OGE_DEFAULT_LIST_VIEW_CONFIG` is the resolved default.