primereact/autocomplete/autocomplete.d.ts

PrimeReact is an open source UI library for React featuring a rich set of 90+ components, a theme designer, various theme alternatives such as Material, Bootstrap, Tailwind, premium templates and professional support. In addition, it integrates with Prime

/**
 *
 * AutoComplete is an input component that provides real-time suggestions while being typed.
 *
 * [Live Demo](https://www.primereact.org/autocomplete/)
 *
 * @module autocomplete
 *
 */
import * as React from 'react';
import { CSSTransitionProps } from '../csstransition';
import { TooltipOptions } from '../tooltip/tooltipoptions';
import { FormEvent } from '../ts-helpers';
import { IconType } from '../utils';
import { VirtualScroller, VirtualScrollerProps } from '../virtualscroller';

/**
 * Custom change event.
 * @see {@link AutoCompleteProps.onChange}
 * @extends {FormEvent}
 * @event
 */
interface AutoCompleteChangeEvent extends FormEvent {}

/**
 * Custom select event.
 * @see {@link AutoCompleteProps.onSelect}
 * @event
 */
interface AutoCompleteSelectEvent {
    /**
     * Browser event
     */
    originalEvent: React.SyntheticEvent;
    /**
     * Selected option value
     */
    value: any;
}

/**
 * Custom unselect event.
 * @see {@link AutoCompleteProps.onUnselect}
 * @extends {AutoCompleteSelectEvent}
 * @event
 */
interface AutoCompleteUnselectEvent extends AutoCompleteSelectEvent {}

/**
 * Custom click event.
 * @see {@link AutoCompleteProps.onDropdownClick}
 * @event
 */
interface AutoCompleteDropdownClickEvent {
    /**
     * Browser event
     */
    originalEvent: React.SyntheticEvent;
    /**
     * Current value of the input field
     */
    query: string;
}

/**
 * Custom complete method event.
 * @see {@link AutoCompleteProps.completeMethod}
 * @event
 */
interface AutoCompleteCompleteEvent {
    /**
     * Browser event
     */
    originalEvent: React.SyntheticEvent;
    /**
     * Value to search with
     */
    query: string;
}

/**
 * Defines valid properties in AutoComplete component. In addition to these, all properties of HTMLSpanElement can be used in this component.
 * @group Properties
 */
export interface AutoCompleteProps extends Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, 'onChange' | 'onSelect' | 'ref'> {
    /**
     * Unique identifier of the element.
     */
    id?: string | undefined;
    /**
     * DOM element instance where the overlay panel should be mounted. Valid values are any DOM Element and "self". The "self" value is used to render a component where it is located.
     * @defaultValue document.body
     */
    appendTo?: 'self' | HTMLElement | undefined | null;
    /**
     * When present, it specifies that the component should automatically get focus on load.
     * @defaultValue false
     */
    autoFocus?: boolean | undefined;
    /**
     * When enabled, highlights the first item in the list by default.
     * @defaultValue false
     */
    autoHighlight?: boolean | undefined;
    /**
     * Style class of the component.
     */
    className?: string | undefined;
    /**
     * Delay between keystrokes to wait before sending a query.
     * @defaultValue 300
     */
    delay?: number | undefined;
    /**
     * When present, it specifies that the component should be disabled.
     * @defaultValue false
     */
    disabled?: boolean | undefined;
    /**
     * Displays a button next to the input field when enabled.
     * @defaultValue false
     */
    dropdown?: boolean | undefined;
    /**
     * ARIA label for the dropdown button. Defaults to placeholder then Locale "choose" label.
     * @defaultValue Choose
     */
    dropdownAriaLabel?: string | undefined;
    /**
     * Focus the input field when the dropdown button is clicked if enabled.
     * @defaultValue true
     */
    dropdownAutoFocus?: boolean | undefined;
    /**
     * Icon class of the dropdown icon.
     * @defaultValue pi pi-chevron-down
     */
    dropdownIcon?: IconType<AutoCompleteProps> | undefined;
    /**
     * Specifies the behavior dropdown button. Default "blank" mode sends an empty string and "current" mode sends the input value.
     * @defaultValue blank
     */
    dropdownMode?: 'blank' | 'current' | undefined;
    /**
     * Text to display when there is no data. Defaults to global value in i18n translation configuration.
     * @defaultValue No results found.
     */
    emptyMessage?: string | undefined;
    /**
     * Field of a suggested object to resolve and display.
     */
    field?: string | undefined;
    /**
     * When present, autocomplete clears the manual input if it does not match of the suggestions to force only accepting values from the suggestions.
     * @defaultValue false
     */
    forceSelection?: boolean | undefined;
    /**
     * Style class of the input field.
     */
    inputClassName?: string | undefined;
    /**
     * Identifier of the input element.
     */
    inputId?: string | undefined;
    /**
     * Reference of the input element.
     */
    inputRef?: React.Ref<HTMLInputElement> | undefined;
    /**
     * Inline style of the input field.
     */
    inputStyle?: React.CSSProperties | undefined;
    /**
     * Template of a list item.
     */
    itemTemplate?: React.ReactNode | ((suggestion: any, index: number) => React.ReactNode);
    /**
     * Maximum number of characters to initiate a search.
     */
    maxLength?: number | undefined;
    /**
     * Minimum number of characters to initiate a search.
     * @defaultValue 1
     */
    minLength?: number | undefined;
    /**
     * Specifies if multiple values can be selected.
     * @defaultValue false
     */
    multiple?: boolean | undefined;
    /**
     * Number of maximum options that can be selected.
     */
    selectionLimit?: number | undefined;
    /**
     * Name of the input element.
     */
    name?: string | undefined;
    /**
     * Property name or getter function that refers to the children options of option group.
     */
    optionGroupChildren?: string | undefined;
    /**
     * Property name or getter function to use as the label of an option group.
     */
    optionGroupLabel?: string | undefined;
    /**
     * Template of an option group item.
     */
    optionGroupTemplate?: React.ReactNode | ((suggestion: any, index: number) => React.ReactNode);
    /**
     * Style class of the overlay panel element.
     */
    panelClassName?: string | undefined;
    /**
     * Inline style of the overlay panel element.
     */
    panelStyle?: React.CSSProperties | undefined;
    /**
     * Hint text for the input field.
     */
    placeholder?: string | undefined;
    /**
     * When present, it specifies that the input cannot be typed.
     * @defaultValue false
     */
    readOnly?: boolean | undefined;
    /**
     * Icon of the remove chip element in multiple mode.
     * @defaultValue pi pi-times-circle
     */
    removeIcon?: IconType<AutoCompleteProps> | undefined;
    /**
     * Maximum height of the suggestions panel.
     * @defaultValue 200px
     */
    scrollHeight?: string | undefined;
    /**
     * Template of a selected item.
     */
    selectedItemTemplate?: React.ReactNode | ((value: any) => React.ReactNode);
    /**
     * Whether to show the empty message or not.
     * @defaultValue false
     */
    showEmptyMessage?: boolean | undefined;
    /**
     * Size of the input field.
     */
    size?: number | undefined;
    /**
     * Inline style of the component.
     */
    style?: React.CSSProperties | undefined;
    /**
     * An array of suggestions to display.
     */
    suggestions?: any[];
    /**
     * Index of the element in tabbing order.
     */
    tabIndex?: number | undefined;
    /**
     * Content of the tooltip.
     */
    tooltip?: string | undefined;
    /**
     * Configuration of the tooltip, refer to the tooltip documentation for more information.
     * @type {TooltipOptions}
     */
    tooltipOptions?: TooltipOptions | undefined;
    /**
     * The properties of CSSTransition can be customized, except for "nodeRef" and "in" properties.
     * @type {CSSTransitionProps}
     */
    transitionOptions?: CSSTransitionProps | undefined;
    /**
     * Type of the input element.
     */
    type?: string | undefined;
    /**
     * Value of the component.
     */
    value?: any;
    /**
     * Whether to use the virtualScroller feature. The properties of VirtualScroller component can be used like an object in it.
     * @type {VirtualScrollerProps}
     */
    virtualScrollerOptions?: VirtualScrollerProps | undefined;
    /**
     * Callback to invoke to search for suggestions.
     * @param {AutoCompleteCompleteEvent} event - Custom complete method event.
     */
    completeMethod?(event: AutoCompleteCompleteEvent): void;
    /**
     * Callback to invoke when autocomplete loses focus.
     * @param {React.FocusEvent<HTMLInputElement>} event - Browser event.
     */
    onBlur?(event: React.FocusEvent<HTMLInputElement>): void;
    /**
     * Callback to invoke when autocomplete value changes.
     * @param {AutoCompleteChangeEvent} event - Custom change event.
     */
    onChange?(event: AutoCompleteChangeEvent): void;
    /**
     * Callback to invoke when input is cleared by the user.
     * @param {React.SyntheticEvent} event - Browser event.
     */
    onClear?(event: React.SyntheticEvent): void;
    /**
     * Callback to invoke on click.
     * @param {React.MouseEvent<HTMLElement>} event - Browser event.
     */
    onClick?(event: React.MouseEvent<HTMLElement>): void;
    /**
     * Callback to invoke on right-click.
     * @param {React.MouseEvent<HTMLElement>} event - Browser event.
     */
    onContextMenu?(event: React.MouseEvent<HTMLElement>): void;
    /**
     * Callback to invoke on double click.
     * @param {React.MouseEvent<HTMLElement>} event - Browser event.
     */
    onDblClick?(event: React.MouseEvent<HTMLElement>): void;
    /**
     * Callback to invoke to when dropdown button is clicked.
     * @param {AutoCompleteDropdownClickEvent} event - Custom click event.
     */
    onDropdownClick?(event: AutoCompleteDropdownClickEvent): void;
    /**
     * Callback to invoke when autocomplete gets focus.
     * @param {React.FocusEvent<HTMLInputElement>} event - Browser event.
     */
    onFocus?(event: React.FocusEvent<HTMLInputElement>): void;
    /**
     * Callback to invoke when overlay panel becomes hidden.
     */
    onHide?(): void;
    /**
     * Callback to invoke to when a key is pressed.
     * @param {React.KeyboardEvent<HTMLInputElement>} event - Browser event.
     */
    onKeyPress?(event: React.KeyboardEvent<HTMLInputElement>): void;
    /**
     * Callback to invoke to when a key is released.
     * @param {React.KeyboardEvent<HTMLInputElement>} event - Browser event.
     */
    onKeyUp?(event: React.KeyboardEvent<HTMLInputElement>): void;
    /**
     * Callback to invoke to when a mouse button is pressed.
     * @param {React.MouseEvent<HTMLElement>} event - Browser event.
     */
    onMouseDown?(event: React.MouseEvent<HTMLElement>): void;
    /**
     * Callback to invoke when a suggestion is selected.
     * @param {AutoCompleteSelectEvent} event - Custom select event.
     */
    onSelect?(event: AutoCompleteSelectEvent): void;
    /**
     * Callback to invoke when overlay panel becomes visible.
     */
    onShow?(): void;
    /**
     * Callback to invoke when a selected value is removed.
     * @param {AutoCompleteUnselectEvent} event - Custom unselect event.
     */
    onUnselect?(event: AutoCompleteUnselectEvent): void;
    /**
     * Used to get the child elements of the component.
     * @readonly
     */
    children?: React.ReactNode | undefined;
}

/**
 * **PrimeReact - AutoComplete**
 *
 * _AutoComplete is an input component that provides real-time suggestions while being typed._
 *
 * [Live Demo](https://www.primereact.org/autocomplete/)
 * --- ---
 * ![PrimeReact](https://primefaces.org/cdn/primereact/images/logo-100.png)
 *
 * @group Component
 */
export declare class AutoComplete extends React.Component<AutoCompleteProps, any> {
    /**
     * Used to show the overlay.
     */
    public show(): void;
    /**
     * Used to hide the overlay.
     */
    public hide(): void;
    /**
     * Used to focus the component.
     */
    public focus(): void;
    /**
     * Used to search new suggestions.
     * @param {React.SyntheticEvent} event - Browser event.
     * @param {string} query - Value to search with.
     * @param {string} [source] - Source type, valid values are 'dropdown' and 'input'
     */
    public search(event: React.SyntheticEvent, query: string, source?: 'dropdown' | 'input' | null | undefined): void;
    /**
     * Used to get container element.
     * @return {HTMLSpanElement} Container element
     */
    public getElement(): HTMLSpanElement;
    /**
     * Used to get input element.
     * @return {HTMLInputElement} Input element
     */
    public getInput(): HTMLInputElement;
    /**
     * Used to get overlay element.
     * @return {HTMLElement} Overlay element
     */
    public getOverlay(): HTMLElement;
    /**
     * Used to get the options of inline virtualScroller component.
     * @return {VirtualScroller} VirtualScroller component
     */
    public getVirtualScroller(): VirtualScroller;
}