Tree select — API

KbqTreeSelect

Selector: kbq-tree-select

Exported as: kbqTreeSelect

Properties

Name	Description
@Input() autoSelect: boolean
@Input() backdropClass: InputSignal
@Input() disabled: boolean
@Input() errorStateMatcher: ErrorStateMatcher	Object used to control when error messages are shown.
@Input() hasBackdrop: boolean
@Input() hiddenItemsText: string
@Input() id: string
@Input() multiline: InputSignalWithTransform	Whether to use a multiline matcher or not. Default is false
@Input() multiple: boolean
@Input() panelClass: InputSignal \| { [key: string]: any; }>	Classes to be passed to the select panel. Supports the same syntax as the `[class]` binding.
@Input() panelMaxHeight: InputSignalWithTransform	Maximum height of the panel's scrollable option list, in pixels. Applied as the `--kbq-select-panel-size-max-height` custom property on the panel. The search field and the footer sit outside the scrollable area and add to the panel's total height. When null, the token default (256px) applies.
@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-panel-size-width-max` token applies.
@Input() panelMinWidth: InputSignalWithTransform	Minimum width of the panel. If minWidth is larger than window width, it will be ignored.
@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 or an empty string, the panel will grow to match the longest option's text. Any other value is used as an exact width, and `panelMinWidth` is not applied.
@Input() placeholder: string
@Input() required: boolean
@Input() searchMinOptionsThreshold: number	Controls when the search functionality is displayed based on the number of available options. Automatically enables search hiding if value provided, even if `defaultOptions.searchMinOptionsThreshold` is provided.
@Input() selectAll: InputSignalWithTransform	Whether to render the "select all" master checkbox above the tree. Multiple selection only. The row acts on the nodes the user can actually toggle — enabled and selectable. Without a search query that covers the whole data set, collapsed branches included; while a query is active it covers only the matches. Enabling it also makes Ctrl/Cmd + A a two-way toggle, so the shortcut and the checkbox never disagree (`selectAllToggle` is implied).
@Input() selectAllHandler: (event: KeyboardEvent, select: KbqTreeSelect) => void	Function for handling the combination Ctrl + A (select all). By default, the internal handler is used.
@Input() selectAllToggle: InputSignalWithTransform	When `true`, a repeated Ctrl/Cmd+A deselects all options. Off by default (Ctrl+A only selects).
@Input() sortComparator: InputSignal<(a: KbqTreeOption, b: KbqTreeOption, options: KbqTreeOption[]) => number>	Function used to sort the values in a select in multiple mode. Follows the same logic as `Array.prototype.sort`.
@Output('closed') closedStream: Observable	Event emitted when the select has been closed.
@Output('onSelectAll') onSelectAll: OutputEmitterRef>	Event emitted whenever the tree's `selectAllOptions()` runs — a click on the `selectAll` master checkbox, the Ctrl/Cmd + A shortcut, or a custom `selectAllHandler` that delegates to it.
@Output('openedChange') openedChange: EventEmitter	Event emitted when the select panel has been toggled. Also serves as the `openedChange` member of the `KbqSiblingPopup` contract — a tooltip sharing this element's host reacts to it, so its emission timing (gated on `panelDoneAnimatingStream`, see `ngOnInit`) matters beyond this output's original consumers.
@Output('opened') openedStream: Observable	Event emitted when the select has been opened.
@Output('selectionChange') selectionChange: OutputEmitterRef	Event emitted when the selected value has been changed by the user.
calculateHiddenItems: () => void
changeDetectorRef: ChangeDetectorRef
controlType: string	A name for this control that can be used by `kbq-form-field`.
customMatcher: Signal
customTagTemplateRef: Signal>
customTrigger: Signal	User-supplied override of the trigger element.
defaultErrorStateMatcher: ErrorStateMatcher
elementRef: ElementRef
empty: boolean
errorState: boolean	Whether the component is in an error state.
firstSelected: any
focused: boolean	Whether the select is focused.
hiddenItems: number
isAttached: boolean	Whether the overlay panel is currently on screen. Part of the `KbqSiblingPopup` contract.
isBrowser: boolean
isEmptySearchResult: boolean
multiSelection: boolean	Whether multiple choice is enabled or not. True if multiple or multiline
multilineMatchList: Signal>	Row container of a multi-selection trigger. Absent for a single value, an empty trigger and a custom matcher or trigger — all of which have no rows for the panel to anchor to.
ngControl: NgControl
onChange: (value: any) => void	`View -> model callback called when value changes`
onTouched: () => void	`View -> model callback called when select has been touched`
optionSelectionChanges: Observable	Combined stream of all of the child options' change events.
options: QueryList
optionsContainer: Signal>	Scrollable option list inside the panel.
overlayDir: CdkConnectedOverlay
overlayMinWidth: string \| number	Minimum width of the overlay panel.
overlayOrigin: ElementRef \| CdkOverlayOrigin	Origin for the overlay panel.
overlayPanelClass: "kbq-select-overlay"	Overlay panel class.
overlayWidth: string \| number	Width of the overlay panel.
panel: Signal>	Reference to the overlay panel element.
panelDoneAnimatingStream: Subject	Emits when the panel element is finished transforming in.
panelOpen: boolean
parentForm: NgForm
parentFormGroup: FormGroupDirective
positions: ConnectedPosition[]	Opens the panel below the trigger, falling back to above it when it does not fit. A third position is appended at runtime by `updatePanelAnchor`: a multiline trigger that has grown taller than the panel gets it anchored to its first row and drawn over the rest of it.
scrollStrategy: ScrollStrategy	Strategy that will be used to handle scrolling while the select panel is open.
search: Signal
selected: any
selectedValues: any
selectionModel: SelectionModel	Deals with the selection logic.
tags: QueryList
transformOrigin: string	The value of the select panel's transform-origin property.
tree: Signal
trigger: Signal>	Trigger - is a clickable field to open select dropdown panel
triggerFontSize: number	The cached font-size of the trigger element.
triggerRect: DOMRect	The last measured value for the trigger's client bounding rect.
triggerValue: string
triggerValues: KbqTreeSelectTriggerValue[]
userInteractionChanges: Observable	Combined stream of all of the child options userInteraction events.
value: any
viewportMargin: number	Minimum space to keep between the overlay and the viewport edge. At least `defaultOffsetY` so CDK's fit check — which runs before the `kbq-connected-overlay_below/_above` gap padding is applied to the pane — stays conservative enough to absorb that padding instead of letting the panel overflow the viewport by the size of the gap.
window: Window
Deprecated offsetY: number	The y-offset of the overlay panel in relation to the trigger.

Name

Description

@Input()

autoSelect: boolean

@Input()

backdropClass: InputSignal

@Input()

disabled: boolean

@Input()

errorStateMatcher: ErrorStateMatcher

Object used to control when error messages are shown.

@Input()

hasBackdrop: boolean

@Input()

hiddenItemsText: string

@Input()

id: string

@Input()

multiline: InputSignalWithTransform

Whether to use a multiline matcher or not. Default is false

@Input()

multiple: boolean

@Input()

panelClass: InputSignal | { [key: string]: any; }>

Classes to be passed to the select panel. Supports the same syntax as the `[class]` binding.

@Input()

panelMaxHeight: InputSignalWithTransform

Maximum height of the panel's scrollable option list, in pixels. Applied as the `--kbq-select-panel-size-max-height` custom property on the panel. The search field and the footer sit outside the scrollable area and add to the panel's total height. When null, the token default (256px) applies.

@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-panel-size-width-max` token applies.

@Input()

panelMinWidth: InputSignalWithTransform

Minimum width of the panel. If minWidth is larger than window width, it will be ignored.

@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 or an empty string, the panel will grow to match the longest option's text. Any other value is used as an exact width, and `panelMinWidth` is not applied.

@Input()

placeholder: string

@Input()

required: boolean

@Input()

searchMinOptionsThreshold: number

Controls when the search functionality is displayed based on the number of available options. Automatically enables search hiding if value provided, even if `defaultOptions.searchMinOptionsThreshold` is provided.

@Input()

selectAll: InputSignalWithTransform

Whether to render the "select all" master checkbox above the tree. Multiple selection only. The row acts on the nodes the user can actually toggle — enabled and selectable. Without a search query that covers the whole data set, collapsed branches included; while a query is active it covers only the matches. Enabling it also makes Ctrl/Cmd + A a two-way toggle, so the shortcut and the checkbox never disagree (`selectAllToggle` is implied).

@Input()

selectAllHandler: (event: KeyboardEvent, select: KbqTreeSelect) => void

Function for handling the combination Ctrl + A (select all). By default, the internal handler is used.

@Input()

selectAllToggle: InputSignalWithTransform

When `true`, a repeated Ctrl/Cmd+A deselects all options. Off by default (Ctrl+A only selects).

@Input()

sortComparator: InputSignal<(a: KbqTreeOption, b: KbqTreeOption, options: KbqTreeOption[]) => number>

Function used to sort the values in a select in multiple mode. Follows the same logic as `Array.prototype.sort`.

@Output('closed')

closedStream: Observable

Event emitted when the select has been closed.

@Output('onSelectAll')

onSelectAll: OutputEmitterRef>

Event emitted whenever the tree's `selectAllOptions()` runs — a click on the `selectAll` master checkbox, the Ctrl/Cmd + A shortcut, or a custom `selectAllHandler` that delegates to it.

@Output('openedChange')

openedChange: EventEmitter

Event emitted when the select panel has been toggled. Also serves as the `openedChange` member of the `KbqSiblingPopup` contract — a tooltip sharing this element's host reacts to it, so its emission timing (gated on `panelDoneAnimatingStream`, see `ngOnInit`) matters beyond this output's original consumers.

@Output('opened')

openedStream: Observable

Event emitted when the select has been opened.

@Output('selectionChange')

selectionChange: OutputEmitterRef

Event emitted when the selected value has been changed by the user.

calculateHiddenItems: () => void

changeDetectorRef: ChangeDetectorRef

controlType: string

A name for this control that can be used by `kbq-form-field`.

customMatcher: Signal

customTagTemplateRef: Signal>

customTrigger: Signal

User-supplied override of the trigger element.

defaultErrorStateMatcher: ErrorStateMatcher

elementRef: ElementRef

empty: boolean

errorState: boolean

Whether the component is in an error state.

firstSelected: any

focused: boolean

Whether the select is focused.

hiddenItems: number

isAttached: boolean

Whether the overlay panel is currently on screen. Part of the `KbqSiblingPopup` contract.

isBrowser: boolean

isEmptySearchResult: boolean

multiSelection: boolean

Whether multiple choice is enabled or not. True if multiple or multiline

multilineMatchList: Signal>

Row container of a multi-selection trigger. Absent for a single value, an empty trigger and a custom matcher or trigger — all of which have no rows for the panel to anchor to.

ngControl: NgControl

onChange: (value: any) => void

`View -> model callback called when value changes`

onTouched: () => void

`View -> model callback called when select has been touched`

optionSelectionChanges: Observable

Combined stream of all of the child options' change events.

options: QueryList

optionsContainer: Signal>

Scrollable option list inside the panel.

overlayDir: CdkConnectedOverlay

overlayMinWidth: string | number

Minimum width of the overlay panel.

overlayOrigin: ElementRef | CdkOverlayOrigin

Origin for the overlay panel.

overlayPanelClass: "kbq-select-overlay"

Overlay panel class.

overlayWidth: string | number

Width of the overlay panel.

panel: Signal>

Reference to the overlay panel element.

panelDoneAnimatingStream: Subject

Emits when the panel element is finished transforming in.

panelOpen: boolean

parentForm: NgForm

parentFormGroup: FormGroupDirective

positions: ConnectedPosition[]

Opens the panel below the trigger, falling back to above it when it does not fit. A third position is appended at runtime by `updatePanelAnchor`: a multiline trigger that has grown taller than the panel gets it anchored to its first row and drawn over the rest of it.

scrollStrategy: ScrollStrategy

Strategy that will be used to handle scrolling while the select panel is open.

search: Signal

selected: any

selectedValues: any

selectionModel: SelectionModel

Deals with the selection logic.

tags: QueryList

transformOrigin: string

The value of the select panel's transform-origin property.

tree: Signal

trigger: Signal>

Trigger - is a clickable field to open select dropdown panel

triggerFontSize: number

The cached font-size of the trigger element.

triggerRect: DOMRect

The last measured value for the trigger's client bounding rect.

triggerValue: string

triggerValues: KbqTreeSelectTriggerValue[]

userInteractionChanges: Observable

Combined stream of all of the child options userInteraction events.

value: any

viewportMargin: number

Minimum space to keep between the overlay and the viewport edge. At least `defaultOffsetY` so CDK's fit check — which runs before the `kbq-connected-overlay_below/_above` gap padding is applied to the pane — stays conservative enough to absorb that padding instead of letting the panel overflow the viewport by the size of the gap.

window: Window

Deprecated

offsetY: number

The y-offset of the overlay panel in relation to the trigger.

Methods

calculateOverlayOffsetX

close

Closes the overlay panel and focuses the host element.

focus

getOverlayOriginElement

Element the overlay is positioned and sized against.

getOverlayRect

getPanelClasses

Returns the full set of classes for the panel: base class, theme and custom `panelClass`.

getPanelTheme

Returns the theme to be used on the panel.

handleClick

handleKeydown

hiddenItemsTextFormatter

isListHeightPinnedToCap

Whether the option list renders at the cap whatever its content is, which a `cdk-virtual-scroll-viewport` does by pinning both its `min-height` and its `max-height` to the token.

isPanelOpen

isRtl

lockOverlayWidthForSearch

Freezes the panel at its rendered width so that filtering the options does not reflow it. Does nothing when the width is already pinned.

onAttached

Callback that is invoked when the overlay panel has been attached.

onBlur

Calls the touched callback only if the panel is closed. Otherwise, the trigger will "blur" to the panel when it opens, causing a false positive.

onFocus

onRemoveSelectedOption

Invoked when an option is clicked.

open

panelKeydownHandler

reanchorPanel

Re-resolves the panel position with the first-row anchor brought up to date. Never call this from a `positionChange` subscriber: CDK records the position it applied AFTER the subscriber returns, so an anchor resolved from inside that frame is overwritten by the pre-anchor position, and `cdkConnectedOverlayLockPosition` then replays that stale one on the next scroll.

resetOverlay

resolveSearchMinOptionsThreshold

setOverlayPosition

subscribeToPanelResize

Re-resolves the anchor while the panel is open. A resize rewraps the trigger's rows and changes the room beside it at once, and CDK re-applies the position on its own, so without this the anchor it resolves against is the one measured for the old viewport.

toggle

triggerKeydownHandler

unsubscribeFromPanelResize

Drops the resize subscription the open set up.

updateErrorState

updateOverlayWidth

Resolves the overlay panel size for the current trigger geometry and stores it for the `cdkConnectedOverlay` width bindings.

updatePanelAnchor

Keeps the first-row anchor in `positions`: a third position that puts the panel just below the trigger's first row and over the rest of it, for a multiline trigger that has grown taller than the panel and fits on neither side of it. The anchor goes last, and the overlay stops at the first position that fits completely, so it is reached exactly when neither `below` nor `above` works. `kbqShouldAnchorPanelToFirstRow` holds the rest of the rule. Returns whether the array changed, so that a caller can skip the reposition an unchanged anchor does not need. Updating the array is all there is to do here — `setOverlayPosition()` rebuilds the strategy and resolves the position again.

withOverlapPosition

Returns `positions` with the first-row anchor added, updated or removed, or `null` when the array already says what it should — so that the caller can skip the change detection an edit would need. The anchor goes LAST. The overlay returns on the first position that fits completely, so an entry at the end is reached exactly when neither the below nor the above position works, which is the rule this implements. Pass `null` to drop it again. The result is meant to be assigned to the field the `cdkConnectedOverlayPositions` input reads, NOT handed to `withPositions()` on the strategy: `CdkConnectedOverlay.ngOnChanges` rebuilds the strategy from that field on ANY input change — the width `lockOverlayWidthForSearch` pins is one — so a list applied only to the strategy would be dropped again without a trace.

KbqTreeSelectChange

Change event object that is emitted when the select value has changed.

Properties

Name	Description
isUserInput: boolean
source: KbqTreeSelect
value: any
values: unknown[]

Name

Description

isUserInput: boolean

source: KbqTreeSelect

value: any

values: unknown[]

KbqTreeSelectTriggerValue

Tree select trigger value type.

type KbqTreeSelectTriggerValue = {
    disabled: boolean;
    value: string;
    viewValue: string;
};

KbqTreeSelectPanelWidth

Deprecated

Tree select panel width type.

type KbqTreeSelectPanelWidth = KbqPanelWidth;

KbqTreeSelectOptions

Options for the `kbq-tree-select` that can be configured using the `KBQ_TREE_SELECT_OPTIONS` injection token.

type KbqTreeSelectOptions = Partial<{
    /**
     * Width of the panel. If set to `auto`, the panel will match the trigger width.
     * If set to null or an empty string, the panel will grow to match the longest option's text.
     */
    panelWidth: KbqPanelWidth;
    /**
     * Minimum width of the panel. If minWidth is larger than window width or property set to null, it will be ignored.
     */
    panelMinWidth: KbqPanelMinWidth;
    /**
     * Maximum width of the panel. Caps growth by content only — it never overrides the trigger width or an
     * explicit `panelWidth`. If null, the `--kbq-panel-size-width-max` token applies.
     */
    panelMaxWidth: KbqPanelMaxWidth;
    /**
     * Maximum height of the panel's scrollable option list. Does not include the search field or the
     * footer. If null, the `--kbq-select-panel-size-max-height` token applies.
     */
    panelMaxHeight: KbqPanelMaxHeight;
    /**
     * Whether to enable hiding search by default if options is less than minimum.
     *
     * - `'auto'` uses `KBQ_SELECT_SEARCH_MIN_OPTIONS_THRESHOLD` as min value.
     * - number - will enables search hiding and uses value as min.
     * @see KBQ_SELECT_SEARCH_MIN_OPTIONS_THRESHOLD
     */
    searchMinOptionsThreshold: 'auto' | number;
}>;

KBQ_TREE_SELECT_OPTIONS

Injection token that can be used to provide the default options for the `kbq-tree-select`.

const KBQ_TREE_SELECT_OPTIONS: InjectionToken<Partial<{ panelWidth: KbqPanelWidth; panelMinWidth: number; panelMaxWidth: number; panelMaxHeight: number; searchMinOptionsThreshold: number | "auto"; }>>;

kbqTreeSelectOptionsProvider

Utility provider for `KBQ_TREE_SELECT_OPTIONS`.

const kbqTreeSelectOptionsProvider: (options: Partial<{ panelWidth: KbqPanelWidth; panelMinWidth: number; panelMaxWidth: number; panelMaxHeight: number; searchMinOptionsThreshold: number | "auto"; }>) => Provider;