Dropdown — API

KbqDropdownContent

Dropdown content that will be rendered lazily once the dropdown is opened.

Selector: ng-template[kbqDropdownContent]

Properties

Name	Description
attached: Subject	Emits when the dropdown content has been attached.
document: Document

Name

Description

attached: Subject

Emits when the dropdown content has been attached.

document: Document

KbqDropdownSearch

Marks a `kbq-form-field` projected into a `kbq-dropdown` as the panel's search field. The panel keeps DOM focus in the field, so arrow keys move the highlighted item while the query stays editable.

Selector: [kbqDropdownSearch]

Exported as: kbqDropdownSearch

Properties

Name	Description
ngControl: NgControl	The form control the query is bound to.

Name

Description

ngControl: NgControl

The form control the query is bound to.

Methods

focus

Focuses the search field.

reset

Clears the search query.

value

The current search query.

KbqDropdownItemAction

Marks a secondary, independently-focusable/clickable element (e.g. a settings link) projected inside a `kbq-dropdown-item` alongside the item's own primary action. Requires the item's host element to be non-interactive (e.g. `

`), since interactive content cannot validly nest inside another interactive element.

Selector: [kbqDropdownItemAction]

Methods

getHostElement

Returns the host DOM element.

isInactive

`progress` takes priority over the action, same as `disabled`.

onClick

Always stops the click from bubbling to the item's own primary click handler. Additionally, blocks the action's own default behavior when the parent item is disabled/loading — `` has no native `disabled`.

KbqDropdownItem

This directive is intended to be used inside an kbq-dropdown tag. It exists mostly to set the role attribute.

Selector: kbq-dropdown-item, [kbq-dropdown-item]

Exported as: kbqDropdownItem

Properties

Name	Description
@Input() disabled: boolean
@Input() progress: InputSignalWithTransform	Whether the dropdown item is in a loading state.
active: WritableSignal	Whether the item is the panel's active item while DOM focus is held elsewhere.
focused: Subject	Stream that emits when the menu item is focused.
highlighted: boolean	Whether the dropdown item is highlighted.
hovered: Subject	Stream that emits when the dropdown item is hovered.
icon: KbqIcon
isNested: boolean	Whether the dropdown item acts as a trigger for a nested dropdown.
itemAction: Signal	Secondary, independently-focusable icon action projected into the item (e.g. a settings link).
parentDropdownPanel: KbqDropdownPanel
textElement: ElementRef

progress: InputSignalWithTransform

Whether the dropdown item is in a loading state.

active: WritableSignal

Whether the item is the panel's active item while DOM focus is held elsewhere.

focused: Subject

Stream that emits when the menu item is focused.

highlighted: boolean

Whether the dropdown item is highlighted.

hovered: Subject

Stream that emits when the dropdown item is hovered.

icon: KbqIcon

isNested: boolean

Whether the dropdown item acts as a trigger for a nested dropdown.

itemAction: Signal

Secondary, independently-focusable icon action projected into the item (e.g. a settings link).

parentDropdownPanel: KbqDropdownPanel

textElement: ElementRef

Methods

checkDisabled

Prevents the default element actions if it is disabled. Bound via `host` metadata.

focus

Focuses the dropdown item and reveals it. The reveal is explicit because the one `focus()` performs implicitly is not portable: WebKit defers it to a later rendering update, where it lands after — and undoes — any scrolling the reader did in the meantime. `preventScroll` is therefore always forced on, overriding `options`.

getHostElement

Returns the host DOM element.

getLabel

Gets the label to be used when determining whether the option should be focused.

getTabIndex

Used to set the `tabindex`.

haltDisabledEvents

handleActionKeydown

Lets Tab move focus between the host and `itemAction` without leaving the dropdown (`stopPropagation` only — the browser's native focus move still happens). Any other Tab press, i.e. actually leaving the item, is left untouched and still closes the dropdown via the panel's `FocusKeyManager.tabOut`. Bound via `host` metadata.

handleMouseEnter

Emits to the hover stream. Bound via `host` metadata.

resetStyles

setActiveStyles

Styles the item as active without focusing it.

setInactiveStyles

Removes the styles applied by `setActiveStyles`.

KbqDropdownStaticContent

Selector: [kbqDropdownStaticContent]

KbqDropdownFooter

Footer that is rendered below the dropdown options panel.

Selector: [kbqDropdownFooter], kbq-dropdown-footer

KbqDropdown

Selector: kbq-dropdown

Exported as: kbqDropdown

Properties

Name	Description
@Input() backdropClass: string	Class to be added to the backdrop element.
@Input() hasBackdrop: boolean	Whether the dropdown has a backdrop.
@Input() navigationWithWrap: InputSignal
@Input() overlapTriggerX: boolean	Whether the dropdown should overlap its trigger horizontally.
@Input() overlapTriggerY: boolean	Whether the dropdown should overlap its trigger vertically.
@Input('class') panelClass: string	This method takes classes set on the host kbq-dropdown element and applies them on the dropdown template that displays in the overlay container. Otherwise, it's difficult to style the containing dropdown from outside the component.
@Input() panelMaxWidth: InputSignalWithTransform	Maximum width of the panel in pixels. Caps how far the panel grows with its content — it never makes the panel narrower than the trigger, and never clamps an explicit `panelWidth`. When null, the `--kbq-dropdown-size-container-width-max` token applies.
@Input() panelMinWidth: InputSignalWithTransform	Minimum width of the panel in pixels. The panel is never narrower than this, nor than its trigger.
@Input() panelWidth: InputSignal	Width of the panel. If set to `auto`, the panel will match the trigger width, but will never be narrower than `panelMinWidth`. If set to null, the panel will grow to match its content. Any other value is used as an exact width, and `panelMinWidth` is not applied.
@Input() safeArea: InputSignalWithTransform	Whether nested dropdowns opened from this dropdown's items use a "safe area": while the pointer moves from a trigger toward its open submenu, sibling items it crosses over on the way don't prematurely close the submenu.
@Input() xPosition: KbqDropdownPositionX	Position of the dropdown in the X axis.
@Input() yPosition: KbqDropdownPositionY	Position of the dropdown in the Y axis.
@Output('closed') closed: EventEmitter	Event emitted when the dropdown is closed.
animationDone: Subject	Emits whenever an animation on the dropdown completes.
classList: { [key: string]: boolean; }	Config object to be passed into the dropdown panel's `[class]` binding
direction: Direction	Layout direction of the dropdown.
isAnimating: boolean	Whether the dropdown is animating.
items: QueryList	List of the items inside of a dropdown.
panelAnimationState: "void" \| "enter"	Current state of the panel animation.
parent: KbqDropdownPanel	Parent dropdown of the current dropdown panel.
Deprecated triggerWidth: string

Name

Description

@Input()

backdropClass: string

Class to be added to the backdrop element.

@Input()

hasBackdrop: boolean

Whether the dropdown has a backdrop.

@Input()

navigationWithWrap: InputSignal

@Input()

overlapTriggerX: boolean

Whether the dropdown should overlap its trigger horizontally.

@Input()

overlapTriggerY: boolean

Whether the dropdown should overlap its trigger vertically.

@Input('class')

panelClass: string

This method takes classes set on the host kbq-dropdown element and applies them on the dropdown template that displays in the overlay container. Otherwise, it's difficult to style the containing dropdown from outside the component.

@Input()

panelMaxWidth: InputSignalWithTransform

Maximum width of the panel in pixels. Caps how far the panel grows with its content — it never makes the panel narrower than the trigger, and never clamps an explicit `panelWidth`. When null, the `--kbq-dropdown-size-container-width-max` token applies.

@Input()

panelMinWidth: InputSignalWithTransform

Minimum width of the panel in pixels. The panel is never narrower than this, nor than its trigger.

@Input()

panelWidth: InputSignal

Width of the panel. If set to `auto`, the panel will match the trigger width, but will never be narrower than `panelMinWidth`. If set to null, the panel will grow to match its content. Any other value is used as an exact width, and `panelMinWidth` is not applied.

@Input()

safeArea: InputSignalWithTransform

Whether nested dropdowns opened from this dropdown's items use a "safe area": while the pointer moves from a trigger toward its open submenu, sibling items it crosses over on the way don't prematurely close the submenu.

@Input()

xPosition: KbqDropdownPositionX

Position of the dropdown in the X axis.

@Input()

yPosition: KbqDropdownPositionY

Position of the dropdown in the Y axis.

@Output('closed')

closed: EventEmitter

Event emitted when the dropdown is closed.

animationDone: Subject

Emits whenever an animation on the dropdown completes.

classList: { [key: string]: boolean; }

Config object to be passed into the dropdown panel's `[class]` binding

direction: Direction

Layout direction of the dropdown.

isAnimating: boolean

Whether the dropdown is animating.

items: QueryList

List of the items inside of a dropdown.

panelAnimationState: "void" | "enter"

Current state of the panel animation.

parent: KbqDropdownPanel

Parent dropdown of the current dropdown panel.

Applies the panel's initial focus, see `applyInitialFocus`.

handleKeydown

Handle a keyboard event from the dropdown, delegating to the appropriate action.

hovered

Stream that emits whenever the hovered dropdown item changes.

onAnimationDone

Callback that is invoked when the panel animation completes.

onAnimationStart

resetActiveItem

Resets the active item in the dropdown. This is used when the dropdown is opened, allowing the user to start from the first option when pressing the down arrow.

resetAnimation

Resets the panel animation to its initial state.

startAnimation

Starts the enter animation.

KbqDropdownTrigger

This directive is intended to be used in conjunction with an kbq-dropdown tag. It is responsible for toggling the display of the provided dropdown instance.

Selector: [kbqDropdownTriggerFor]

Exported as: kbqDropdownTrigger

Properties

Name	Description
@Input('kbqDropdownTriggerData') data: any	Data to be passed along to any lazily-rendered content.
@Input() demoteOverlay: boolean	Whether to demote the overlay container z-index so that dropdown overlays sit below sibling overlays (tooltips, modals, etc.). Set to `false` to keep the dropdown overlay at the default overlay container z-index.
@Input('kbqDropdownTriggerFor') dropdown: KbqDropdownPanel	References the dropdown instance that the trigger is associated with.
@Input() offsetX: number	Position offset of the dropdown in the X axis.
@Input() offsetY: number	Position offset of the dropdown in the Y axis.
@Input() openByArrowDown: boolean
@Input('kbqDropdownTriggerRestoreFocus') restoreFocus: boolean	Whether focus should be restored when the menu is closed. Note that disabling this option can have accessibility implications and it's up to you to manage focus, if you decide to turn it off.
@Output('dropdownClosed') dropdownClosed: EventEmitter	Event emitted when the associated dropdown is closed. Kept as an `@Output()` EventEmitter (not `output()`): `KbqOptionActionComponent` subscribes to it via `.pipe()` through the KBQ_OPTION_ACTION_PARENT contract, which an `OutputEmitterRef` does not support — see #DS-5079.
@Output('dropdownOpened') dropdownOpened: OutputEmitterRef	Event emitted when the associated dropdown is opened.
dir: Direction	The text direction of the containing app.
isAttached: boolean	Whether the dropdown overlay is currently attached. Part of the `KbqSiblingPopup` contract. `opened` is set synchronously right after the overlay is attached and, on close, only once the exit animation is done — i.e. it stays `true` for the whole time the trigger is busy with its panel, including the moment `destroy()` restores focus to the trigger.
isBrowser: boolean
lastDestroyReason: DropdownCloseReason
opened: boolean	Whether the dropdown is open.
openedBy: "touch" \| "mouse" \| "keyboard"
openedChange: Observable	Emits `true` when the dropdown opens and `false` when it closes. Part of the `KbqSiblingPopup` contract.

Name

Description

@Input('kbqDropdownTriggerData')

data: any

Data to be passed along to any lazily-rendered content.

@Input()

demoteOverlay: boolean

Whether to demote the overlay container z-index so that dropdown overlays sit below sibling overlays (tooltips, modals, etc.). Set to `false` to keep the dropdown overlay at the default overlay container z-index.

@Input('kbqDropdownTriggerFor')

dropdown: KbqDropdownPanel

References the dropdown instance that the trigger is associated with.

@Input()

offsetX: number

Position offset of the dropdown in the X axis.

@Input()

offsetY: number

Position offset of the dropdown in the Y axis.

@Input()

openByArrowDown: boolean

@Input('kbqDropdownTriggerRestoreFocus')

restoreFocus: boolean

Whether focus should be restored when the menu is closed. Note that disabling this option can have accessibility implications and it's up to you to manage focus, if you decide to turn it off.

@Output('dropdownClosed')

dropdownClosed: EventEmitter

Event emitted when the associated dropdown is closed. Kept as an `@Output()` EventEmitter (not `output()`): `KbqOptionActionComponent` subscribes to it via `.pipe()` through the KBQ_OPTION_ACTION_PARENT contract, which an `OutputEmitterRef` does not support — see #DS-5079.

@Output('dropdownOpened')

dropdownOpened: OutputEmitterRef

Event emitted when the associated dropdown is opened.

dir: Direction

The text direction of the containing app.

isAttached: boolean

Whether the dropdown overlay is currently attached. Part of the `KbqSiblingPopup` contract. `opened` is set synchronously right after the overlay is attached and, on close, only once the exit animation is done — i.e. it stays `true` for the whole time the trigger is busy with its panel, including the moment `destroy()` restores focus to the trigger.

isBrowser: boolean

lastDestroyReason: DropdownCloseReason

opened: boolean

Whether the dropdown is open.

openedBy: "touch" | "mouse" | "keyboard"

openedChange: Observable

Emits `true` when the dropdown opens and `false` when it closes. Part of the `KbqSiblingPopup` contract.

Focuses the dropdown trigger.

handleClick

Handles click events on the trigger.

handleKeydown

Handles key presses on the trigger.

handleMouseLeave

Starts safe-area protection when the pointer leaves a trigger whose submenu is open, so a sibling item crossed on the way to the submenu doesn't prematurely close it.

handleMousedown

Handles mouse presses on the trigger.

isNested

Whether the dropdown triggers a nested dropdown or a top-level one.

open

Opens the dropdown.

toggle

Toggles the dropdown between the open and closed states.

Interfaces

KbqDropdownDefaultOptions

Default `kbq-dropdown` options that can be overridden.

Properties

Name	Description
backdropClass: string	Class to be applied to the dropdown's backdrop.
hasBackdrop: boolean	Whether the dropdown has a backdrop.
overlapTriggerX: boolean	Whether the dropdown should overlap the dropdown trigger horizontally.
overlapTriggerY: boolean	Whether the dropdown should overlap the dropdown trigger vertically.
panelMaxWidth: number	Maximum width of the panel. Caps growth by content only — it never overrides the trigger width or an explicit `panelWidth`. If null, the `--kbq-dropdown-size-container-width-max` token applies.
panelMinWidth: number	Minimum width of the panel. If set to null, only the trigger width applies.
panelWidth: KbqPanelWidth	Width of the panel. If set to `auto`, the panel will match the trigger width. If set to null, the panel will grow to match its content.
safeArea: boolean	Whether nested dropdowns opened from this dropdown's items use a "safe area": while the pointer moves from a trigger toward its open submenu, sibling items it crosses over on the way don't prematurely close the submenu.
xPosition: KbqDropdownPositionX	The x-axis position of the dropdown.
yPosition: KbqDropdownPositionY	The y-axis position of the dropdown.

Name

Description

backdropClass: string

Class to be applied to the dropdown's backdrop.

hasBackdrop: boolean

Whether the dropdown has a backdrop.

overlapTriggerX: boolean

Whether the dropdown should overlap the dropdown trigger horizontally.

overlapTriggerY: boolean

Whether the dropdown should overlap the dropdown trigger vertically.

panelMaxWidth: number

Maximum width of the panel. Caps growth by content only — it never overrides the trigger width or an explicit `panelWidth`. If null, the `--kbq-dropdown-size-container-width-max` token applies.

panelMinWidth: number

Minimum width of the panel. If set to null, only the trigger width applies.

panelWidth: KbqPanelWidth

Width of the panel. If set to `auto`, the panel will match the trigger width. If set to null, the panel will grow to match its content.

safeArea: boolean

Whether nested dropdowns opened from this dropdown's items use a "safe area": while the pointer moves from a trigger toward its open submenu, sibling items it crosses over on the way don't prematurely close the submenu.

xPosition: KbqDropdownPositionX

The x-axis position of the dropdown.

yPosition: KbqDropdownPositionY

The y-axis position of the dropdown.

Type aliases

KbqDropdownPositionX

Position of the dropdown panel along the x-axis.

type KbqDropdownPositionX = 'before' | 'after' | 'center';

KbqDropdownPositionY

Position of the dropdown panel along the y-axis.

type KbqDropdownPositionY = 'above' | 'below';

DropdownCloseReason

Reason why the menu was closed.

type DropdownCloseReason = void | 'click' | 'keydown' | 'tab';

Constants

fadeInItems

const fadeInItems: AnimationTriggerMetadata;

transformDropdown

const transformDropdown: AnimationTriggerMetadata;

KBQ_DROPDOWN_SCROLL_STRATEGY

Injection token that determines the scroll handling while the dropdown is open. The root default keeps the trigger usable outside `KbqDropdownModule`'s injector; providing the token anywhere still wins over it.

const KBQ_DROPDOWN_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;

NESTED_HOVER_SWITCH_DELAY

Grace period before switching to a different nested trigger hovered while a safe area is protecting the currently open submenu. Without it, sweeping the pointer down a long list of nested triggers on the way to the submenu would flicker each row's submenu open and closed.

const NESTED_HOVER_SWITCH_DELAY: number;

KBQ_DROPDOWN_HOST

Marker provided by host components that create their own stacking context at the default overlay z-index (e.g. `KbqTopBar`, `KbqNavbar` use `position: sticky` + `z-index: $overlay-z-index`). When this token is available in the injector tree, `KbqDropdownTrigger` defaults `demoteOverlay` to `false` so the dropdown overlay is not lowered below the host. An explicit `[demoteOverlay]` binding on the trigger still wins.

const KBQ_DROPDOWN_HOST: InjectionToken<unknown>;

NESTED_PANEL_TOP_PADDING

Default top padding of the nested dropdown panel.

const NESTED_PANEL_TOP_PADDING: number;

NESTED_PANEL_LEFT_PADDING

const NESTED_PANEL_LEFT_PADDING: number;

KBQ_DROPDOWN_DEFAULT_OPTIONS

Injection token to be used to override the default options for `kbq-dropdown`.

const KBQ_DROPDOWN_DEFAULT_OPTIONS: InjectionToken<KbqDropdownDefaultOptions>;