`), since interactive content
cannot validly nest inside another interactive element.
```ts
@Directive({ selector: '[kbqDropdownItemAction]' })
class KbqDropdownItemAction {
getHostElement(): HTMLElement;
}
```
- `getHostElement()`: `HTMLElement` — Returns the host DOM element.
#### KbqDropdownItemCaption (directive)
Secondary line of a `kbq-dropdown-item`, shown under the item's text.
```ts
@Directive({ selector: '[kbqDropdownItemCaption]' })
class KbqDropdownItemCaption {}
```
#### KbqDropdownSearch (directive)
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.
```ts
@Directive({ selector: '[kbqDropdownSearch]', exportAs: 'kbqDropdownSearch' })
class KbqDropdownSearch {
get ngControl(): NgControl | null;
focus(): void;
reset(): void;
value(): string;
}
```
- `ngControl`: `NgControl | null` — The form control the query is bound to.
- `focus()`: `void` — Focuses the search field.
- `reset()`: `void` — Clears the search query.
- `value()`: `string` — The current search query.
#### KbqDropdownStaticContent (directive)
```ts
@Directive({ selector: '[kbqDropdownStaticContent]' })
class KbqDropdownStaticContent {}
```
#### KbqDropdownTrigger (directive)
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.
```ts
@Directive({
selector: '[kbqDropdownTriggerFor]',
exportAs: 'kbqDropdownTrigger'
})
class KbqDropdownTrigger implements KbqSiblingPopup {
readonly offsetX = model
();
readonly offsetY = input();
readonly data = input(undefined, {
alias: 'kbqDropdownTriggerData'
});
readonly openByArrowDown = model(true);
readonly origin = input(null, {
alias: 'kbqDropdownTriggerOrigin'
});
readonly autoFocus = input(true, {
alias: 'kbqDropdownTriggerAutoFocus'
});
readonly restoreFocus = model(true, {
alias: 'kbqDropdownTriggerRestoreFocus'
});
readonly dropdown = input(undefined, {
alias: 'kbqDropdownTriggerFor'
});
readonly dropdownOpened = output();
readonly dropdownClosed = output();
lastDestroyReason: DropdownCloseReason;
readonly openedChange: Observable;
openedBy: Exclude | undefined;
get dir(): Direction;
get opened(): boolean;
get isAttached(): boolean;
isNested(): boolean;
toggle(): void;
updatePosition(): void;
open(): void;
close(): void;
focus(origin?: FocusOrigin, options?: FocusOptions): void;
handleMousedown(event: MouseEvent): void;
handleMouseLeave(event: MouseEvent): void;
handleKeydown(event: KeyboardEvent): void;
handleClick(event: MouseEvent): void;
}
```
- `[(offsetX)]`: `number | undefined` — Position offset of the dropdown in the X axis.
- `[offsetY]`: `number | undefined` — Position offset of the dropdown in the Y axis.
- `[kbqDropdownTriggerData]`: `any` — Data to be passed along to any lazily-rendered content.
- `[(openByArrowDown)]`: `boolean` — Whether the Down Arrow opens the dropdown when the trigger is focused. Written by `kbq-navbar-item`.
- `[kbqDropdownTriggerOrigin]`: `KbqOverlayOrigin | null` — What the panel is positioned against: an element, or a rectangle in viewport coordinates such as the one
`kbqCreateCaretOrigin` keeps on the caret. `null` anchors the panel to the trigger element.
Call `updatePosition` to move an open panel to a new origin.
- `[kbqDropdownTriggerAutoFocus]`: `boolean` — Whether opening the dropdown moves the keyboard focus into the panel. Turn it off to leave focus where it
is — in the editor the panel is anchored to, for instance — and pair it with `activeDescendantNavigation`
on the panel so the arrow keys still work.
- `[(kbqDropdownTriggerRestoreFocus)]`: `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.
- `[kbqDropdownTriggerFor]`: `KbqDropdownPanel` — References the dropdown instance that the trigger is associated with.
- `(dropdownOpened)`: `void` — Event emitted when the associated dropdown is opened.
- `(dropdownClosed)`: `void` — Event emitted when the associated dropdown is closed.
- `openedChange`: `Observable` — Emits `true` when the dropdown opens and `false` when it closes. Part of the `KbqSiblingPopup` contract.
- `dir`: `Direction` — The text direction of the containing app.
- `opened`: `boolean` — Whether the dropdown is open.
- `isAttached`: `boolean` — Whether the dropdown overlay is currently attached. Part of the `KbqSiblingPopup` contract.
Set right after the overlay is attached and cleared right after it is detached, once `destroy()` has
restored focus to the trigger, so a tooltip on the trigger stays muted for that focus.
- `isNested()`: `boolean` — Whether the dropdown triggers a nested dropdown or a top-level one.
- `toggle()`: `void` — Toggles the dropdown between the open and closed states.
- `updatePosition()`: `void` — Moves an open panel to the current origin and re-applies its position.
- `open()`: `void` — Opens the dropdown.
- `close()`: `void` — Closes the dropdown.
- `focus()`: `void` — Focuses the dropdown trigger.
- `handleMousedown()`: `void` — Handles mouse presses on the trigger.
- `handleMouseLeave()`: `void` — 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.
- `handleKeydown()`: `void` — Handles key presses on the trigger.
- `handleClick()`: `void` — Handles click events on the trigger.
### Types
#### DropdownCloseReason (type)
Reason why the menu was closed.
```ts
type DropdownCloseReason = void | 'click' | 'keydown' | 'tab';
```
#### KbqDropdownDefaultOptions (interface)
Default `kbq-dropdown` options that can be overridden.
```ts
interface KbqDropdownDefaultOptions {
xPosition: KbqDropdownPositionX;
yPosition: KbqDropdownPositionY;
overlapTriggerX: boolean;
overlapTriggerY: boolean;
backdropClass: string;
hasBackdrop: boolean;
safeArea?: boolean;
panelWidth?: KbqPanelWidth;
panelMinWidth?: KbqPanelMinWidth;
panelMaxWidth?: KbqPanelMaxWidth;
}
```
- `xPosition`: `KbqDropdownPositionX` — The x-axis position of the dropdown.
- `yPosition`: `KbqDropdownPositionY` — The y-axis position of the dropdown.
- `overlapTriggerX`: `boolean` — Whether the dropdown should overlap the dropdown trigger horizontally.
- `overlapTriggerY`: `boolean` — Whether the dropdown should overlap the dropdown trigger vertically.
- `backdropClass`: `string` — Class to be applied to the dropdown's backdrop.
- `hasBackdrop`: `boolean` — Whether the dropdown has a backdrop.
- `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.
- `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.
- `panelMinWidth?`: `KbqPanelMinWidth` — Minimum width of the panel. If set to null, only the trigger width applies.
- `panelMaxWidth?`: `KbqPanelMaxWidth` — 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.
#### KbqDropdownPositionX (type)
Position of the dropdown panel along the x-axis.
```ts
type KbqDropdownPositionX = 'before' | 'after' | 'center';
```
#### KbqDropdownPositionY (type)
Position of the dropdown panel along the y-axis.
```ts
type KbqDropdownPositionY = 'above' | 'below';
```
### Constants
#### KBQ_DROPDOWN_DEFAULT_OPTIONS (const)
Injection token to be used to override the default options for `kbq-dropdown`.
```ts
const KBQ_DROPDOWN_DEFAULT_OPTIONS: InjectionToken;
```
#### KBQ_DROPDOWN_SCROLL_STRATEGY (const)
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.
```ts
const KBQ_DROPDOWN_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
```
#### NESTED_HOVER_SWITCH_DELAY (const)
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.
```ts
const NESTED_HOVER_SWITCH_DELAY: number;
```
#### NESTED_PANEL_LEFT_PADDING (const)
```ts
const NESTED_PANEL_LEFT_PADDING: number;
```
#### NESTED_PANEL_TOP_PADDING (const)
Default top padding of the nested dropdown panel.
```ts
const NESTED_PANEL_TOP_PADDING: number;
```