Tabs API
Full surface of @oge-ui/tabs: the oge-tab-panel strip-with-content component, the stand-alone oge-tabs strip, the declarative <oge-tab> child and the config provider.
Properties Methods Events Types
OgeTabPanel
oge-tab-panelProperties 20
Tabs & selection
| Name | Type | Default | Description |
|---|---|---|---|
items | readonly OgeTabItem[] | undefined | — | Data-driven tabs rendered after the projected <oge-tab> children. |
selectedIndex | number | 0 | Index of the selected tab — two-way. -1 selects none; clamped when tabs are removed. |
selectedKey | string | undefined | undefined | Key of the selected tab — two-way, reconciled with selectedIndex both ways. |
activation | 'automatic' | 'manual' | 'automatic' | APG activation: arrows select immediately, or move focus only until Enter/Space commits. |
disabled | boolean | false | Disables the whole component. |
ariaLabel | string | undefined | — | Aria label of the tablist. |
messages | Partial<OgeTabsMessages> | {} | Per-instance overrides of the config messages. |
Closing, overflow & order
| Name | Type | Default | Description |
|---|---|---|---|
closable | boolean | false | Default closability; overridable per tab / per item. Closed tabs are removed by the app in tabClosed. The ✕ is presentational — the keyboard path is Delete/Backspace on the focused tab. |
showNavButtons | 'auto' | 'always' | 'never' | 'auto' | Overflow nav arrows; auto shows them only while the strip overflows. |
showTabListButton | boolean | false | Shows the all-tabs overflow menu (an oge-menu-list with the active tab checked). |
allowTabReordering | boolean | false | Enables drag & drop reordering of tab headers; Escape cancels an in-flight drag. |
Appearance
| Name | Type | Default | Description |
|---|---|---|---|
stylingMode | 'primary' | 'secondary' | 'primary' | Visual variant: underline ink (primary) or soft pills (secondary). |
size | 'sm' | 'md' | 'lg' | 'md' | Density of the tab strip. |
tabAlignment | 'start' | 'center' | 'end' | 'justify' | 'stretch' | 'start' | Distribution of the tabs while they fit: justify spreads them to the edges, stretch gives every tab an equal share. |
indicatorFit | 'tab' | 'content' | 'tab' | Whether the selected-tab indicator spans the whole tab or only its label area. |
Panel rendering (oge-tab-panel only)
| Name | Type | Default | Description |
|---|---|---|---|
tabsPosition | 'top' | 'bottom' | 'start' | 'end' | 'top' | Side the strip sits on — logical values, so RTL flips start/end. Vertical positions switch the arrow keys to Up/Down. |
deferRendering | boolean | true | Instantiate a panel's content only when its tab first activates (lazy templates via ogeTabContentTemplate). |
keepAlive | boolean | true | Keep once-rendered panels mounted (hidden) so state survives switches; false destroys lazy content on deactivation. |
panelAnimation | 'none' | 'fade' | 'slide' | 'none' | Transition played by the incoming panel; slide enters from the direction of travel (mirrored in RTL). Duration comes from --oge-tab-panel-transition (180ms) and is suppressed under prefers-reduced-motion. |
dynamicHeight | boolean | false | Animates the content box between the outgoing and incoming panel heights instead of jumping; async content is tracked with a ResizeObserver. |
Methods 3
| Name | Type | Description |
|---|---|---|
focus(): void | void | Focuses the active tab header (roving-tabindex target). |
closeTab(target: number | string): void | void | Runs the close pipeline (tabClosing → closeGuard → tabClosed) for an index or key. |
scrollToTab(target: number | string): void | void | Scrolls the tab at an index or with a key into view. |
Events 7
| Name | Type | Description |
|---|---|---|
selectionChanging | OgeTabSelectionChangingEvent | Cancelable pre-event of a user-gesture selection change (cancel = true keeps the current tab). Programmatic model writes bypass it. |
selectionChanged | OgeTabSelectionChangedEvent | After the selection committed — index/key/previousIndex/previousKey/item/event. |
tabClick | OgeTabClickEvent | A tab header was activated by pointer or keyboard (Enter/Space). |
tabClosing | OgeTabClosingEvent | Cancelable pre-event of a close, before the async closeGuard runs. |
tabClosed | OgeTabClosedEvent | The close passed all guards — remove the items entry or <oge-tab> here. |
tabReordering | OgeTabReorderingEvent | Cancelable pre-event of a drag-reorder drop (fromIndex/toIndex/key). |
tabReordered | OgeTabReorderedEvent | A drag reorder committed to the display order. |
OgeTabs
oge-tabsProperties 16
Strip (oge-tabs only)
| Name | Type | Default | Description |
|---|---|---|---|
orientation | 'horizontal' | 'vertical' | 'horizontal' | Strip direction; vertical renders a column, maps arrows to Up/Down and sets aria-orientation. |
Tabs & selection
| Name | Type | Default | Description |
|---|---|---|---|
items | readonly OgeTabItem[] | undefined | — | Data-driven tabs rendered after the projected <oge-tab> children. |
selectedIndex | number | 0 | Index of the selected tab — two-way. -1 selects none; clamped when tabs are removed. |
selectedKey | string | undefined | undefined | Key of the selected tab — two-way, reconciled with selectedIndex both ways. |
activation | 'automatic' | 'manual' | 'automatic' | APG activation: arrows select immediately, or move focus only until Enter/Space commits. |
disabled | boolean | false | Disables the whole component. |
ariaLabel | string | undefined | — | Aria label of the tablist. |
messages | Partial<OgeTabsMessages> | {} | Per-instance overrides of the config messages. |
Closing, overflow & order
| Name | Type | Default | Description |
|---|---|---|---|
closable | boolean | false | Default closability; overridable per tab / per item. Closed tabs are removed by the app in tabClosed. The ✕ is presentational — the keyboard path is Delete/Backspace on the focused tab. |
showNavButtons | 'auto' | 'always' | 'never' | 'auto' | Overflow nav arrows; auto shows them only while the strip overflows. |
showTabListButton | boolean | false | Shows the all-tabs overflow menu (an oge-menu-list with the active tab checked). |
allowTabReordering | boolean | false | Enables drag & drop reordering of tab headers; Escape cancels an in-flight drag. |
Appearance
| Name | Type | Default | Description |
|---|---|---|---|
stylingMode | 'primary' | 'secondary' | 'primary' | Visual variant: underline ink (primary) or soft pills (secondary). |
size | 'sm' | 'md' | 'lg' | 'md' | Density of the tab strip. |
tabAlignment | 'start' | 'center' | 'end' | 'justify' | 'stretch' | 'start' | Distribution of the tabs while they fit: justify spreads them to the edges, stretch gives every tab an equal share. |
indicatorFit | 'tab' | 'content' | 'tab' | Whether the selected-tab indicator spans the whole tab or only its label area. |
Methods 3
| Name | Type | Description |
|---|---|---|
focus(): void | void | Focuses the active tab header (roving-tabindex target). |
closeTab(target: number | string): void | void | Runs the close pipeline (tabClosing → closeGuard → tabClosed) for an index or key. |
scrollToTab(target: number | string): void | void | Scrolls the tab at an index or with a key into view. |
Events 7
| Name | Type | Description |
|---|---|---|
selectionChanging | OgeTabSelectionChangingEvent | Cancelable pre-event of a user-gesture selection change (cancel = true keeps the current tab). Programmatic model writes bypass it. |
selectionChanged | OgeTabSelectionChangedEvent | After the selection committed — index/key/previousIndex/previousKey/item/event. |
tabClick | OgeTabClickEvent | A tab header was activated by pointer or keyboard (Enter/Space). |
tabClosing | OgeTabClosingEvent | Cancelable pre-event of a close, before the async closeGuard runs. |
tabClosed | OgeTabClosedEvent | The close passed all guards — remove the items entry or <oge-tab> here. |
tabReordering | OgeTabReorderingEvent | Cancelable pre-event of a drag-reorder drop (fromIndex/toIndex/key). |
tabReordered | OgeTabReorderedEvent | A drag reorder committed to the display order. |
OgeTab
oge-tabProperties 9
| Name | Type | Default | Description |
|---|---|---|---|
text | string | '' | Tab label; alternative to an inline [ogeTabHeaderTemplate]. |
key | string | undefined | — | Stable identity used by selectedKey, reorder tracking and DOM ids. |
disabled | boolean | false | Disabled tabs are skipped by keyboard navigation and selection. |
visible | boolean | true | false removes the tab (and its panel) entirely. |
closable | boolean | undefined | undefined | Shows a close button; undefined falls back to the component-level closable. |
badge | string | number | undefined | — | Badge rendered after the label. |
dirty | boolean | false | Renders the unsaved-changes dot and announces it to screen readers (messages.dirty). |
hint | string | undefined | — | Tooltip — rendered as the native title attribute. |
closeGuard | () => boolean | Promise<boolean> | — | Veto hook run before this tab closes; may be async (single-flight, rejection = veto, pending spinner on the ✕). |
Types 2
Template slots
| Name | Type | Description |
|---|---|---|
[ogeTabHeaderTemplate] | OgeTabHeaderTemplateContext | Custom tab header (icons, rich markup). Inside an <oge-tab>: that tab only; directly inside the component: every items tab. Context: { $implicit: item, index, selected, text }. |
[ogeTabContentTemplate] | OgeTabContentTemplateContext | Lazily instantiated panel content. Inside an <oge-tab> it replaces the projected content; directly inside oge-tab-panel it renders every items tab. Context: { $implicit: item, index }. |
Tabs configuration
Properties 2
| Name | Type | Description |
|---|---|---|
provideOgeTabsConfig(config) | (config: OgeTabsConfigInput) => Provider | Application- or component-scoped defaults; shallow-merges messages over the built-ins. |
messages | OgeTabsMessages | Every user-facing string: closeTab, scrollBackward, scrollForward, tabListMenu, dirty, noData. |
Types 10
| Name | Type | Description |
|---|---|---|
OgeTabItem | { key?, text?, badge?, hint?, disabled?, visible?, closable?, dirty?, closeGuard? } | One data-driven tab of the items input. |
OgeTabCloseGuard | () => boolean | Promise<boolean> | Per-tab veto hook; resolving false (or rejecting) keeps the tab open. |
OgeTabsActivation | 'automatic' | 'manual' | How keyboard focus interacts with selection (APG). |
OgeTabsPosition | 'top' | 'bottom' | 'start' | 'end' | Logical strip placement of oge-tab-panel. |
OgeTabsOrientation | 'horizontal' | 'vertical' | Direction of a stand-alone oge-tabs strip. |
OgeTabsNavButtonsMode | 'auto' | 'always' | 'never' | When the overflow nav arrows are shown. |
OgeTabsAlignment | 'start' | 'center' | 'end' | 'justify' | 'stretch' | How tabs are distributed along the strip. |
OgeTabsIndicatorFit | 'tab' | 'content' | Width of the selected-tab indicator. |
OgeTabPanelAnimation | 'none' | 'fade' | 'slide' | Transition played by the newly displayed panel. |
OgeTabsStylingMode / OgeTabsSize | 'primary' | 'secondary' / 'sm' | 'md' | 'lg' | Visual variant and density unions. |