Toolbar API
Full surface of the oge-toolbar container, the declarative <oge-toolbar-item> child, the three projection slots and the config provider.
Properties Methods Events Types
OgeToolbar
oge-toolbarProperties 21
Items
| Name | Type | Default | Description |
|---|---|---|---|
items | readonly OgeToolbarItemData[] | undefined | — | Data-driven entries, rendered after the declarative <oge-toolbar-item> children. |
dataSource | DataSource<OgeToolbarItemData> | undefined | — | Remote command list, loaded through @oge-ui/core’s DataSource contract and merged after items. A source that publishes changes triggers a reload. |
showText | 'always' | 'onBar' | 'inMenu' | 'never' | 'always' | Default for every item’s showText: both places, the bar only, the menu only, or neither. An item that renders icon-only keeps its text as the accessible name. |
showIcon | 'always' | 'onBar' | 'inMenu' | 'never' | 'always' | Default for every item’s showIcon. It resolves separately for the bar and the overflow menu, so a collapsed command keeps its icon on its menu row unless you say 'onBar'. |
Layout & overflow
| Name | Type | Default | Description |
|---|---|---|---|
overflow | 'menu' | 'scroll' | 'wrap' | 'extended' | 'none' | 'menu' | menu collapses what does not fit into an overflow menu, scroll keeps one line and adds scroll buttons, wrap flows onto more lines (the reference multiline mode), extended hides the remainder in a second row behind a toggle, none lets the row overflow. |
scrollStep | number | 120 | Pixels a scroll button moves the row in overflow: 'scroll'. |
orientation | 'horizontal' | 'vertical' | 'horizontal' | Main axis. Drives the arrow keys and aria-orientation (written only when vertical, since horizontal is the ARIA default). |
size | 'sm' | 'md' | 'lg' | 'md' | Density preset. Falls back to provideOgeToolbarConfig({ size }). |
stylingMode | 'outlined' | 'filled' | 'flat' | 'outlined' | Container chrome. Falls back to provideOgeToolbarConfig({ stylingMode }). |
State & accessibility
| Name | Type | Default | Description |
|---|---|---|---|
disabled | boolean | false | Disables every item and takes the whole toolbar out of the Tab sequence. |
wrap | boolean | true | Whether arrow navigation wraps around the ends — optional in the APG toolbar pattern, on by default here. |
keyboardNavigation | boolean | true | Turns arrow/Home/End handling off entirely. The controls then keep their natural Tab order instead of a roving tabindex. |
itemHoldTimeout | number | 750 | Milliseconds a pointer must rest on an item before itemHold fires. |
ariaLabel | string | undefined | — | Accessible name of the toolbar; falls back to messages.toolbar. |
ariaLabelledBy | string | undefined | — | Id of a visible label. Wins over ariaLabel, which is then omitted. |
messages | Partial<OgeToolbarMessages> | undefined | — | Per-instance overrides of the config strings (toolbar, overflowMenu, noData). |
Template slots
| Name | Type | Default | Description |
|---|---|---|---|
ogeToolbarBefore | attribute slot | — | Projects any control into the leading group. Slot content always stays on the bar — the toolbar cannot re-stamp DOM it does not own. |
ogeToolbarCenter | attribute slot | — | Projects any control into the centre group. |
ogeToolbarAfter | attribute slot | — | Projects any control into the trailing group. |
ogeToolbarItemTemplate | TemplateRef<OgeToolbarItemTemplateContext> | — | Replaces the default rendering of every items entry — the curated stand-in for the reference libraries’ string-keyed widget + options bag. Declared inside an <oge-toolbar-item> it renders that one item instead, and stays re-stampable into the menu. |
ogeToolbarMenuItemTemplate | TemplateRef<OgeToolbarItemTemplateContext> | — | Replaces the default rendering of an item inside the overflow menu (the reference menuItemTemplate). |
Methods 11
Methods
| Name | Type | Description |
|---|---|---|
focus() | (): void | Focuses the toolbar’s current roving-tabindex stop. |
openMenu() | (event?: Event): void | Opens the overflow menu. Runs the menuOpening pipeline, so it can be vetoed. |
closeMenu() | (reason?: OgeToolbarMenuCloseReason): void | Closes the overflow menu, subject to menuClosing. Defaults to reason 'api'. |
toggleMenu() | (event?: Event): void | Opens the menu when closed, closes it otherwise — the reference toggle() method. |
toggleExtendedRow() | (): void | Shows or hides the second row of overflow: 'extended'. |
refreshOverflow() | (): void | Drops the measurement cache and re-measures. Signal changes and container resizes already do this — call it after something the toolbar cannot observe changed a control’s size (a late web font, a stylesheet swap). |
addItem() | (item: OgeToolbarItemData): void | Appends a runtime entry, merged after items. items stays the declared source of truth, so a re-supplied array does not drop it. |
removeItem() | (key: string): void | Drops an entry added by addItem(), or hides an items entry. |
hideItem() | (key: string, hidden?: boolean): void | Hides (or re-shows) an entry without touching the items array. |
enableItem() | (key: string, enabled?: boolean): void | Enables (or disables) an entry without touching the items array. |
clearItemOverrides() | (): void | Drops every hideItem() / enableItem() override. |
Events 9
Events
| Name | Type | Description |
|---|---|---|
itemClick | OgeToolbarItemClickEvent | An item was activated on the bar or from the menu. Payload: index, key, item, inMenu, event. |
menuOpening | OgeToolbarMenuOpeningEvent | Cancelable — set cancel to keep the overflow menu closed. |
menuOpened | void | The overflow menu opened. |
menuClosing | OgeToolbarMenuClosingEvent | Cancelable — set cancel to keep the overflow menu open. Carries the close reason. |
menuClosed | OgeToolbarMenuClosedEvent | The overflow menu closed, with its reason. |
overflowChanged | OgeToolbarOverflowChangedEvent | The set of items living in the overflow menu changed. Payload: keys, count. |
activeChanged | OgeToolbarItemActiveChangedEvent | A toggle item’s pressed state changed. items entries are data the toolbar must not mutate, so this is how the new value reaches the app; a declarative child also writes its two-way active model. |
itemHold | OgeToolbarItemHoldEvent | An item was held for itemHoldTimeout — touch long-press or mouse hold. |
itemContextMenu | OgeToolbarItemHoldEvent | An item was right-clicked or long-pressed. |
Types 20
Types
| Name | Type | Description |
|---|---|---|
OgeToolbarItemData | interface | One data-driven entry: key, type, text, icon, suffixIcon, iconClass, suffixIconClass, hint, width, htmlAttributes, location, locateInMenu, overflowPriority, showText, showIcon, disabled, visible, cssClass, severity, active, data. |
OgeToolbarItemType | 'button' | 'separator' | 'spacer' | 'label' | What the toolbar renders for an item it owns. |
OgeToolbarItemLocation | 'before' | 'center' | 'after' | Which of the three groups an item belongs to. |
OgeToolbarLocateInMenu | 'auto' | 'always' | 'never' | Whether an item may move into the overflow menu. Structurally core’s OgeToolbarOverflowPolicy, which fitToolbarItems() consumes. |
OgeToolbarDisplayMode | 'always' | 'onBar' | 'inMenu' | 'never' | Where an item’s text or icon is rendered: both places, the bar only, the menu only, or neither. |
OgeToolbarItemSeverity | 'default' | 'accent' | 'danger' | Emphasis of an item the toolbar renders itself. |
OgeToolbarOverflow | 'menu' | 'scroll' | 'wrap' | 'extended' | 'none' | How the toolbar reacts to more items than room. |
OgeToolbarOrientation | 'horizontal' | 'vertical' | Main axis of the toolbar. |
OgeToolbarSize | 'sm' | 'md' | 'lg' | Density preset. |
OgeToolbarStylingMode | 'outlined' | 'filled' | 'flat' | Container chrome preset. |
OgeToolbarMenuCloseReason | 'api' | 'outside' | 'escape' | 'select' | 'tab' | Why the overflow menu closed — the overlay package’s canonical reason set. |
OgeToolbarItemClickEvent | interface | index, key?, item?, inMenu, event. |
OgeToolbarOverflowChangedEvent | interface | keys, count. |
OgeToolbarItemActiveChangedEvent | interface | index, key?, item?, active, event. |
OgeToolbarItemHoldEvent | interface | Payload of itemHold and itemContextMenu: index, key?, item?, event. |
OgeToolbarMenuOpeningEvent | interface | cancel, event?. |
OgeToolbarMenuClosingEvent | interface | cancel, reason. |
OgeToolbarMenuClosedEvent | interface | reason. |
OgeToolbarItemTemplateContext | interface | $implicit (the items entry, undefined for declarative children), index, inMenu. |
fitToolbarItems | (options: OgeToolbarFitOptions) => OgeToolbarFitResult | The framework-free fitting math in @oge-ui/core: which items fit and which collapse. Pure arithmetic, so it is unit-testable without a DOM — the component only feeds it measurements. |
OgeToolbarItem
oge-toolbar-itemProperties 21
Inputs
| Name | Type | Default | Description |
|---|---|---|---|
key | string | undefined | — | Stable identity echoed on itemClick and used for DOM ids. |
type | 'button' | 'separator' | 'spacer' | 'label' | 'button' | What the toolbar renders when the item has no inline template. |
text | string | undefined | — | Label; also the accessible name when the item renders icon-only. |
icon | string | undefined | — | SVG path data (d) for a leading aria-hidden 16×16 icon. |
suffixIcon | string | undefined | — | SVG path data (d) for a trailing icon, rendered after the text. |
iconClass | string | undefined | — | Class(es) for a leading icon rendered as an empty <i> — the hook for an icon font the application already ships. icon stays the dependency-free default. |
suffixIconClass | string | undefined | — | Class(es) for a trailing icon element. |
width | number | string | undefined | — | Fixed main-axis size of the item — a bare number is pixels. |
htmlAttributes | Readonly<Record<string, string>> | undefined | — | Extra attributes on the item element. Keys removed from the bag are removed from the DOM, so clearing it clears the element. |
hint | string | undefined | — | Tooltip — the native title attribute. |
location | 'before' | 'center' | 'after' | 'before' | Which of the toolbar’s three groups the item joins. |
locateInMenu | 'auto' | 'always' | 'never' | 'auto' | Whether the item may move into the overflow menu. The default diverges from the reference never on purpose — collapsing is the point. |
overflowPriority | number | undefined | 0 | How hard the item holds its place on the bar; higher survives longer. The default makes the trailing item yield first, as in every reference toolbar. Raise it to keep a primary command visible without moving it to the front of the bar. |
showText | 'always' | 'onBar' | 'inMenu' | 'never' | undefined | — | Overrides the toolbar’s showText. |
showIcon | 'always' | 'onBar' | 'inMenu' | 'never' | undefined | — | Overrides the toolbar’s showIcon. |
disabled | boolean | false | Not clickable, and skipped by the toolbar’s arrow navigation. |
visible | boolean | true | false removes the item entirely. |
cssClass | string | undefined | — | Extra class on the item element. |
severity | 'default' | 'accent' | 'danger' | 'default' | Emphasis of a toolbar-rendered button. |
data | unknown | — | Arbitrary payload echoed back on itemClick — the declarative counterpart of the same field on an [items] entry. |
active | boolean | undefined (two-way) | — | Toggle-button state. Defining it is what makes the item a toggle: it renders aria-pressed on the bar and a checkmark in the menu, and every activation flips the value. |
Events 2
Events
| Name | Type | Description |
|---|---|---|
itemClick | OgeToolbarItemClickEvent | This item was activated, on the bar or from the overflow menu. Saves the index lookup the toolbar-level event needs. |
activeChanged | OgeToolbarItemActiveChangedEvent | This toggle item’s pressed state changed. |
Toolbar configuration
Properties 8
provideOgeToolbarConfig()
| Name | Type | Default | Description |
|---|---|---|---|
size | 'sm' | 'md' | 'lg' | undefined | — | Default for every toolbar’s size. |
stylingMode | 'outlined' | 'filled' | 'flat' | undefined | — | Default for every toolbar’s stylingMode. |
messages.toolbar | string | 'Toolbar' | Accessible name used when neither ariaLabel nor ariaLabelledBy is set. |
messages.overflowMenu | string | 'More commands' | Accessible name and tooltip of the overflow button, and the menu’s label. |
messages.moreCommands | string | 'Show more commands' | Accessible name of the overflow: 'extended' second-row toggle. |
messages.scrollBackward | string | 'Scroll backward' | Accessible name of the back scroll button in overflow: 'scroll'. |
messages.scrollForward | string | 'Scroll forward' | Accessible name of the forward scroll button. |
messages.noData | string | 'No commands to display' | Shown when the toolbar has no items of its own and nothing is projected into a slot (the reference noDataText). |