Buttons API

Complete API reference for @oge-ui/buttons — every input, output, imperative method and supporting type, compiled from the source TSDoc. Cancelable and gesture behavior is documented on the demo pages.

Properties Methods Events Types

OgeButton

oge-button

Properties 24

Appearance

Name	Type	Default	Description
`text`	`string`	`''`	Label text; alternative (or addition) to projecting content.
`hint`	`string \| undefined`	—	Tooltip — rendered as the native `title` attribute.
`stylingMode`	`OgeButtonStylingMode \| undefined`	—	Fill style; falls back to the enclosing group, then `contained`.
`severity`	`OgeButtonSeverity \| undefined`	—	Semantic color; falls back to the enclosing group, then `normal`.
`size`	`OgeButtonSize \| undefined`	—	Size preset; falls back to the enclosing group, then `md`.
`color`	`string \| undefined`	—	Custom main color (any CSS color) — overrides the severity palette; the soft tint is derived via `color-mix`.
`iconPosition`	`OgeButtonIconPosition`	`'before'`	Where `[ogeButtonIcon]` content renders relative to the label.
`badge`	`string \| number \| boolean \| undefined`	—	String/number renders a pill (numbers cap at `99+` and join the accessible name); `true` renders a plain dot.

Behavior

Name	Type	Default	Description
`disabled`	`boolean`	`false`	Disables the button.
`loading`	`model<boolean>`	`false`	Busy state — two-way; managed automatically while `action` is pending.
`action`	`(() => unknown) \| undefined`	—	Async click handler: sets `loading` while pending, single-flight; sync returns emit `actionDone` immediately.
`clickGuard`	`boolean \| OgeClickGuardOptions`	`false`	Rate-limits the `clicked` output; `true` throttles with `config.clickGuardMs`.
`holdToConfirm`	`boolean \| OgeHoldToConfirmOptions`	`false`	Fires `clicked` only after an uninterrupted press; wins over `autoRepeat`. `true` uses `config.holdToConfirmMs`.
`autoRepeat`	`boolean \| OgeAutoRepeatOptions`	`false`	Repeats `clicked` while held; ignored when `holdToConfirm` is set.
`useSubmitBehavior`	`boolean`	`false`	Renders `type="submit"` so the button submits the enclosing form.
`buttonType`	`'button' \| 'submit' \| 'reset'`	`'button'`	Native button type; `useSubmitBehavior` is sugar for `submit`.
`value`	`string \| undefined`	—	Selection key inside an `<oge-button-group>`; unused standalone.
`tabIndex`	`number`	`0`	Tab order of the native button.
`accessKey`	`string \| undefined`	—	Native `accesskey` of the inner button.
`messages`	`Partial<OgeButtonsMessages> \| undefined`	—	Per-instance overrides of user-facing strings.

Accessibility

Name	Type	Default	Description
`ariaLabel`	`string \| undefined`	—	Accessible name of the native button — required for icon-only buttons.
`ariaHasPopup`	`string \| undefined`	—	`aria-haspopup` of the native button — for popup triggers.
`ariaExpanded`	`boolean \| undefined`	—	`aria-expanded`; `undefined` omits the attribute.
`ariaControls`	`string \| undefined`	—	`aria-controls` — id of the controlled popup.

Methods 2

Name	Type	Description
`focus(): void`	`void`	Moves keyboard focus to the inner native button (`preventScroll: true`).
`isDisabled`	`Signal<boolean>`	Read-only computed: disabled, busy, or inside a disabled group.

Events 4

Name	Type	Description
`clicked`	`OgeButtonClickEvent`	Fires after the gesture/guard pipeline accepts a click. Bind this instead of native `(click)`, which bypasses every guard.
`actionDone`	`OgeButtonActionDoneEvent`	The `action` callback settled successfully.
`actionFailed`	`OgeButtonActionFailedEvent`	The `action` callback threw or rejected.
`loadingChange`	`boolean`	Implicit output of the `loading` model.

Types 11

Name	Type	Description
`OgeButtonStylingMode`	`'contained' \| 'outlined' \| 'text'`	Fill style.
`OgeButtonSeverity`	`'normal' \| 'accent' \| 'success' \| 'warning' \| 'danger'`	Semantic color mapped to the severity tokens.
`OgeButtonSize`	`'sm' \| 'md' \| 'lg'`	Height/padding preset.
`OgeButtonIconPosition`	`'before' \| 'after'`	Icon slot placement.
`OgeButtonClickEvent`	`{ event: MouseEvent \| KeyboardEvent }`	`KeyboardEvent` when produced by Space/Enter during hold/repeat.
`OgeButtonActionDoneEvent`	`{ result: unknown }`	Resolved value (or sync return) of `action`.
`OgeButtonActionFailedEvent`	`{ error: unknown }`	Rejection reason or thrown error of `action`.
`OgeClickGuardOptions`	`{ mode: 'debounce' \| 'throttle'; ms?: number }`	`ms` defaults to `config.clickGuardMs`; `true` shorthand ≡ throttle.
`OgeHoldToConfirmOptions`	`{ ms?: number }`	Hold duration; defaults to `config.holdToConfirmMs`.
`OgeAutoRepeatOptions`	`{ delayMs?: number; intervalMs?: number }`	Defaults from `config.autoRepeatDelayMs` / `autoRepeatIntervalMs`.
`OgeButtonIcon`	`directive — [ogeButtonIcon]`	Marks projected content as the icon slot; placement follows `iconPosition`.

OgeButtonGroup

oge-button-group

Properties 8

Name	Type	Default	Description
`items`	`readonly OgeButtonGroupItem[] \| undefined`	—	Data-driven items rendered after projected `<oge-button>` children.
`selectionMode`	`OgeButtonGroupSelectionMode`	`'none'`	Selection behavior; also drives the ARIA role (toolbar / radiogroup / group).
`selectedKeys`	`model<readonly string[]>`	`[]`	Selected `value`s — two-way; `single` keeps at most one entry.
`stylingMode`	`OgeButtonStylingMode`	`'contained'`	Cascaded to children without their own.
`severity`	`OgeButtonSeverity`	`'normal'`	Cascaded to children without their own.
`size`	`OgeButtonSize`	`'md'`	Cascaded to children without their own.
`disabled`	`boolean`	`false`	Disables every button in the group.
`ariaLabel`	`string \| undefined`	—	Accessible name of the toolbar/radiogroup/group element.

Methods 2

Name	Type	Description
`focus(): void`	`void`	Moves keyboard focus to the roving-tabindex target button.
`isSelected(value: string \| undefined): boolean`	`boolean`	Whether the given button `value` is currently selected (reactive).

Events 3

Name	Type	Description
`itemClick`	`OgeButtonGroupItemClickEvent`	Every accepted child click, before any selection change.
`selectionChanged`	`OgeButtonGroupSelectionChangedEvent`	`selectedKeys` changed through user interaction.
`selectedKeysChange`	`readonly string[]`	Implicit output of the `selectedKeys` model.

Types 4

Name	Type	Description
`OgeButtonGroupSelectionMode`	`'none' \| 'single' \| 'multiple'`	Selection behavior of the group.
`OgeButtonGroupItem`	`{ value: string; text?; hint?; disabled?; severity?; badge? }`	Data-driven item; icons require declarative children.
`OgeButtonGroupItemClickEvent`	`{ value: string \| undefined; event: MouseEvent \| KeyboardEvent; item?: OgeButtonGroupItem; index: number }`	`index` is DOM-order; `-1` when unresolvable.
`OgeButtonGroupSelectionChangedEvent`	`{ selectedKeys: readonly string[]; addedKeys: readonly string[]; removedKeys: readonly string[] }`	Full state plus diffs.

OgeDropDownButton

oge-drop-down-button

Properties 21

Trigger button

Name	Type	Default	Description
`text`	`string`	`''`	Label of the (main) trigger button.
`hint`	`string \| undefined`	—	Tooltip of the trigger.
`disabled`	`boolean`	`false`	Disables the whole control.
`stylingMode`	`OgeButtonStylingMode \| undefined`	—	Same fallback chain as `OgeButton`.
`severity`	`OgeButtonSeverity \| undefined`	—	Same fallback chain as `OgeButton`.
`size`	`OgeButtonSize \| undefined`	—	Same fallback chain as `OgeButton`.
`color`	`string \| undefined`	—	Custom main color — overrides the severity palette.
`iconPosition`	`OgeButtonIconPosition`	`'before'`	Icon slot placement on the trigger.
`badge`	`string \| number \| boolean \| undefined`	—	Badge on the trigger, as on `OgeButton`.
`splitButton`	`boolean`	`false`	`true` renders a separate chevron toggle next to an action main button.
`action`	`(() => unknown) \| undefined`	—	Async click handler of the split main button (single-flight, drives `loading`).
`clickGuard`	`boolean \| OgeClickGuardOptions`	`false`	Click guard of the split main button.
`loading`	`model<boolean>`	`false`	Busy state of the (main) button — two-way.
`messages`	`Partial<OgeButtonsMessages> \| undefined`	—	Per-instance overrides of user-facing strings (status rows, toggle label).

Drop-down panel

Name	Type	Default	Description
`items`	`readonly OgeMenuItem[] \| OgeDropDownItemsFn \| undefined`	—	Menu items — an array, or a function invoked lazily on first open (result cached until the function reference changes).
`opened`	`model<boolean>`	`false`	Panel visibility — two-way.
`dropdownPlacement`	`OgePopupPlacement`	`'bottom-start'`	Preferred panel placement (flips/clamps automatically).
`dropdownWidth`	`number \| 'anchor' \| undefined`	—	Fixed pixels or `'anchor'` to match the button width.
`adaptiveMode / adaptiveBreakpoint`	`'auto' \| 'none' / number`	`config: 'none' / 600`	`'auto'` opens the menu as a modal bottom sheet (title from `text` / `hint`, close button, 44px rows, focus trap, Escape / backdrop / swipe dismiss) on viewports narrower than `adaptiveBreakpoint` px; `'none'` keeps the anchored menu. App-wide defaults come from `provideOgeButtonsConfig()`.
`rememberLastAction`	`boolean`	`false`	Split mode: the last clicked item becomes the main button's label + action.
`itemTemplate`	`TemplateRef<OgeMenuItemTemplateContext> \| undefined`	—	Custom rendering for menu items — see `OgeMenuList`.

Methods 5

Name	Type	Description
`open(): void`	`void`	Opens the panel programmatically.
`close(): void`	`void`	Closes the panel programmatically.
`toggle(): void`	`void`	Toggles `opened`.
`focus(): void`	`void`	Focuses the trigger (split mode: the chevron toggle).
`panel`	`OgeAnchoredPanel`	The anchored-panel model — public so templates/tests can read `panelId`.

Events 7

Name	Type	Description
`itemClick`	`OgeDropDownButtonItemClickEvent`	Menu item activated; the panel closes afterwards.
`selectionChanged`	`OgeDropDownSelectionChangedEvent`	`rememberLastAction` mode: the remembered item changed.
`clicked`	`OgeButtonClickEvent`	Split mode only: the main action button was clicked. In non-split mode the trigger only toggles the panel.
`actionDone`	`OgeButtonActionDoneEvent`	The split-button `action` settled successfully.
`actionFailed`	`OgeButtonActionFailedEvent`	The split-button `action` threw or rejected.
`openedChange`	`boolean`	Implicit output of the `opened` model — fires on both open and close.
`loadingChange`	`boolean`	Implicit output of the `loading` model.

Types 4

Name	Type	Description
`OgeDropDownItemsFn`	`() => readonly OgeMenuItem[] \| Promise<readonly OgeMenuItem[]>`	Lazy items factory — invoked on first open.
`OgeDropDownButtonItemClickEvent`	`{ item: OgeMenuItem; index: number; event: MouseEvent \| KeyboardEvent }`	Index within the resolved items list (separators included).
`OgeDropDownSelectionChangedEvent`	`{ item: OgeMenuItem; previousItem: OgeMenuItem \| null }`	Remembered-item change in `rememberLastAction` mode.
`OgeDropDownContent`	`directive — [ogeDropDownContent]`	Replaces the item menu with arbitrary panel content; context `{ $implicit: () => void }` closes the panel and restores focus.

Buttons configuration

Methods 1

Name	Type	Description
`provideOgeButtonsConfig(config: OgeButtonsConfigInput): Provider`	`Provider`	Application- or component-scoped defaults; deep-merges `messages` over the defaults.

Types 15

OgeButtonsConfig

Name	Type	Default	Description
`clickGuardMs`	`number`	`500`	Default window for `clickGuard: true` and guard options without `ms`.
`holdToConfirmMs`	`number`	`800`	Default hold duration for `holdToConfirm: true`.
`autoRepeatDelayMs`	`number`	`400`	Delay before `autoRepeat` starts repeating.
`autoRepeatIntervalMs`	`number`	`80`	Interval between repeated clicks.
`adaptiveMode`	`'auto' \| 'none'`	`'none'`	Default `adaptiveMode` of the drop-down button.
`adaptiveBreakpoint`	`number`	`600`	Viewport width (px) below which `'auto'` opens the menu as a bottom sheet.
`messages`	`OgeButtonsMessages`	—	User-facing strings (see below).

OgeButtonsMessages

Name	Type	Default	Description
`loading`	`string`	`'Loading'`	Screen-reader text announced while a button is busy.
`holdToConfirm`	`string`	`'Hold to confirm'`	Tooltip fragment when `holdToConfirm` is enabled.
`dropDownLoading`	`string`	`'Loading…'`	Status row while a drop-down loads async items.
`dropDownNoItems`	`string`	`'No items'`	Status row when a drop-down has no items.
`dropDownLoadError`	`string`	`'Could not load items'`	Status row when async items failed to load.
`dropDownToggle`	`string`	`'Open menu'`	Aria label of the split drop-down's chevron toggle.
`adaptiveClose`	`string`	`'Close'`	Aria label of the adaptive menu sheet's close button.
`adaptiveTitle`	`string`	`'Actions'`	Sheet title when the button has no `text` or `hint`.

Notes

Outputs never reuse native DOM event names — bind (clicked), not (click); native events still bubble from the host and bypass every guard.
onInitialized/onOptionChanged/onContentReady lifecycle callbacks are intentionally absent — Angular lifecycle, effect() and signal inputs cover them.