import { KbqAutocompleteModule } from '@koobiq/components/autocomplete';

KbqAutocomplete

componentCopy link to KbqAutocomplete
@Component({ selector: 'kbq-autocomplete', exportAs: 'kbqAutocomplete' })
class KbqAutocomplete implements KbqOptionParentComponent {
    readonly displayWith = input<((value: any) => string) | null>(null);
    readonly panelWidth = input<KbqPanelWidth | undefined>();
    readonly panelMinWidth = input<number>(KBQ_PANEL_DEFAULT_MIN_WIDTH);
    readonly panelMaxWidth = input<KbqPanelMaxWidth>(null);
    readonly hostClass = input<string>('', { alias: 'class' });
    readonly autoActiveFirstOption = input<boolean>(
        !!this.defaultOptions.autoActiveFirstOption
    );
    readonly openOnFocus = input<boolean>(true);
    readonly optionSelected = output<KbqAutocompleteSelectedEvent>();
    readonly opened = output<void>();
    readonly closed = output<void>();
    readonly id: string;
    readonly template: Signal<TemplateRef<any>>;
    readonly panel: Signal<ElementRef<any>>;
    get options(): QueryList<KbqOption>;
    readonly optionGroups: Signal<readonly KbqOptgroup[]>;
    readonly isOpen: Signal<boolean>;
}
displayWithinputCopy link to displayWith((value: any) => string) | null

Function that maps an option's control value to its display value in the trigger.

panelWidthinputCopy link to panelWidthKbqPanelWidth | undefined

Specify the width of the autocomplete panel. If set to auto, the panel will match the width of its host, but will never be narrower than panelMinWidth. Any other CSS sizing value is used as an exact width, and panelMinWidth is not applied. When not set, the panel sizes to its content and is at least as wide as its host.

panelMinWidthinputCopy link to panelMinWidthnumber

Minimum width of the panel in pixels. When panelWidth is not set, the panel will be at least as wide as its host and no less than panelMinWidth.

panelMaxWidthinputCopy link to panelMaxWidthKbqPanelMaxWidth

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

classinputCopy link to classstring

Classes set on the host kbq-autocomplete element. They are applied to the panel inside the overlay container instead, to allow for easy styling.

Accepts every shape Angular's own [class] binding does. The binding value arrives here raw: Angular converts it to a string before handing it to a styling-shadowing input only when the element carries a static class attribute, which <kbq-autocomplete> does not.

autoActiveFirstOptioninputCopy link to autoActiveFirstOptionboolean

Whether the first option should be highlighted when the autocomplete panel is opened. Can be configured globally through the KBQ_AUTOCOMPLETE_DEFAULT_OPTIONS token.

openOnFocusinputCopy link to openOnFocusboolean

Whether the panel opens as soon as the trigger receives focus.

optionSelectedoutputCopy link to optionSelectedKbqAutocompleteSelectedEvent

Event that is emitted whenever an option from the list is selected.

openedoutputCopy link to openedvoid

Event that is emitted when the autocomplete panel is opened.

closedoutputCopy link to closedvoid

Event that is emitted when the autocomplete panel is closed.

idCopy link to idstring

Unique id, rendered as the panel element's id.

isOpenCopy link to isOpenSignal<boolean>

Whether the panel is visible: attached by the trigger and holding at least one option.

KbqAutocompleteFooter

directiveCopy link to KbqAutocompleteFooter

Footer that is rendered below the autocomplete options panel.

@Directive({ selector: '[kbqAutocompleteFooter], kbq-autocomplete-footer' })
class KbqAutocompleteFooter {}

KbqAutocompleteOrigin

directiveCopy link to KbqAutocompleteOrigin

Directive applied to an element to make it usable as a connection point for an autocomplete panel.

@Directive({
    selector: '[kbqAutocompleteOrigin]',
    exportAs: 'kbqAutocompleteOrigin'
})
class KbqAutocompleteOrigin {
    elementRef: ElementRef<HTMLElement>;
}

KbqAutocompleteTrigger

directiveCopy link to KbqAutocompleteTrigger
@Directive({
    selector: 'input[kbqAutocomplete], textarea[kbqAutocomplete]',
    exportAs: 'kbqAutocompleteTrigger'
})
class KbqAutocompleteTrigger implements ControlValueAccessor, KeyboardNavigationHandler, KbqSiblingPopup {
    readonly autocomplete = input<KbqAutocomplete>(undefined, {
        alias: 'kbqAutocomplete'
    });
    readonly connectedTo = input<KbqAutocompleteOrigin>(undefined, {
        alias: 'kbqAutocompleteConnectedTo'
    });
    readonly autocompleteDisabled = input<boolean>(false, {
        alias: 'kbqAutocompleteDisabled'
    });
    readonly onInputBlur = input<(event: FocusEvent) => boolean>(
        (event: FocusEvent): boolean => {
            const target: HTMLElement = event.relatedTarget as HTMLElement;

            return !target || target.tagName !== 'KBQ-OPTION';
        },
        { alias: 'kbqAutocompleteOnBlur' }
    );
    readonly relativeToCaret = input<boolean>(false, {
        alias: 'kbqAutocompleteRelativeToCaret'
    });
    readonly textMode = input<boolean>(false, {
        alias: 'kbqAutocompleteTextMode'
    });
    readonly queryTriggers = input<readonly string[]>([], {
        alias: 'kbqAutocompleteTriggers'
    });
    readonly queryMinLength = input<number | undefined>(undefined, {
        alias: 'kbqAutocompleteMinLength'
    });
    readonly inlineHint = input<boolean>(true, {
        alias: 'kbqAutocompleteInlineHint'
    });
    readonly queryChange = output<KbqTextQuery | null>({
        alias: 'kbqAutocompleteQueryChange'
    });
    get activeOption(): KbqOption | null;
    get panelOpen(): boolean;
    get isAttached(): boolean;
    readonly openedChange: Observable<boolean>;
    readonly optionSelections: Observable<KbqOptionSelectionChange>;
    get panelClosingActions(): Observable<KbqOptionSelectionChange | null>;
    open(): void;
    closePanel(): void;
    updatePosition(): void;
    handleKeydown(event: KeyboardEvent): void;
    handleInput(event: Event): void;
    handleFocus(): void;
    handleClick($event: Event): void;
    scrollActiveOptionIntoView(): void;
}
kbqAutocompleteinputCopy link to kbqAutocompleteKbqAutocomplete

The autocomplete panel to be attached to this trigger.

kbqAutocompleteConnectedToinputCopy link to kbqAutocompleteConnectedToKbqAutocompleteOrigin

Reference relative to which to position the autocomplete panel. Defaults to the autocomplete trigger element.

kbqAutocompleteDisabledinputCopy link to kbqAutocompleteDisabledboolean

Whether the autocomplete is disabled. When disabled, the element will act as a regular input and the user won't be able to open the panel.

kbqAutocompleteOnBlurinputCopy link to kbqAutocompleteOnBlur(event: FocusEvent) => boolean

Event handler for input blur events. Determines whether the blur event is triggered outside the specific target

kbqAutocompleteRelativeToCaretinputCopy link to kbqAutocompleteRelativeToCaretboolean

Whether the panel opens from the text caret instead of the field: its left edge at the caret, right below the caret's line, following the caret while it moves. The panel is only as wide as its options — panelMinWidth does not apply there, an explicit panelWidth still does.

kbqAutocompleteTextModeinputCopy link to kbqAutocompleteTextModeboolean

Whether the autocomplete completes the text at the caret instead of the whole value. The query is the word before the caret, or the text after one of kbqAutocompleteTriggers; choosing an option replaces the query, trigger included, with the option. The form value stays the whole text.

kbqAutocompleteTriggersinputCopy link to kbqAutocompleteTriggersreadonly string[]

Strings that start a query in text mode, such as / or @. When empty, the query is the word before the caret.

kbqAutocompleteMinLengthinputCopy link to kbqAutocompleteMinLengthnumber | undefined

Shortest query that opens the panel in text mode. Defaults to 1 for a word and to 0 after a trigger.

kbqAutocompleteInlineHintinputCopy link to kbqAutocompleteInlineHintboolean

Whether text mode draws the rest of the active option after the caret, to be accepted with Tab or →. The field has to be inside kbq-form-field.

kbqAutocompleteQueryChangeoutputCopy link to kbqAutocompleteQueryChangeKbqTextQuery | null

Emits the query at the caret in text mode whenever it changes, or null once there is none. The query is read again as the user types or clicks in the field, and as the caret moves while the panel is open. It carries the trigger it starts with, which tells apart the options to show for each trigger.

activeOptionCopy link to activeOptionKbqOption | null

The currently active option, coerced to MatOption type.

isAttachedCopy link to isAttachedboolean

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

openedChangeCopy link to openedChangeObservable<boolean>

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

Built on top of the autocomplete signal rather than read once: the panel is bound after the consumers of this stream are created (a tooltip on the same element subscribes in its constructor).

panelClosingActionsCopy link to panelClosingActionsObservable<KbqOptionSelectionChange | null>

A stream of actions that should close the autocomplete panel, including when an option is selected, on blur, and when TAB is pressed.

open()Copy link to open()void

Opens the autocomplete suggestion panel.

updatePosition()Copy link to updatePosition()void

Updates the position of the autocomplete suggestion panel to ensure that it fits all options within the viewport.

KbqAutocompleteSelectedEvent

classCopy link to KbqAutocompleteSelectedEvent
class KbqAutocompleteSelectedEvent {
    source: KbqAutocomplete;
    option: KbqOption;
    constructor(source: KbqAutocomplete, option: KbqOption);
}

KBQ_AUTOCOMPLETE_DEFAULT_OPTIONS_FACTORY

functionCopy link to KBQ_AUTOCOMPLETE_DEFAULT_OPTIONS_FACTORY
function KBQ_AUTOCOMPLETE_DEFAULT_OPTIONS_FACTORY(): KbqAutocompleteDefaultOptions;

KbqAutocompleteDefaultOptions

interfaceCopy link to KbqAutocompleteDefaultOptions

Default kbq-autocomplete options that can be overridden.

interface KbqAutocompleteDefaultOptions {
    autoActiveFirstOption?: boolean;
}
autoActiveFirstOptionoptionalCopy link to autoActiveFirstOptionboolean

Whether the first option should be highlighted when an autocomplete panel is opened.

KBQ_AUTOCOMPLETE_DEFAULT_OPTIONS

constCopy link to KBQ_AUTOCOMPLETE_DEFAULT_OPTIONS

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

const KBQ_AUTOCOMPLETE_DEFAULT_OPTIONS: InjectionToken<KbqAutocompleteDefaultOptions>;

KBQ_AUTOCOMPLETE_SCROLL_STRATEGY

constCopy link to KBQ_AUTOCOMPLETE_SCROLL_STRATEGY

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

const KBQ_AUTOCOMPLETE_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
Suggestions for improvement
If you found a mistake or want to improve the article, create an issue on GitHub.