@blinkstrike/chakra-ui-autocomplete/dist/index.d.ts

An accessible autocomplete utility library built for chakra UI

import React from 'react';
import { UseMultipleSelectionProps } from 'downshift';
import { ResponsiveValue, BoxProps } from '@chakra-ui/react';
import { IconProps } from '@chakra-ui/icons';
/**
 * Interface for each item in the autocomplete dropdown.
 */
export interface Item {
    label: string;
    value: string;
}
/**
 * Props for the CUIAutoComplete component.
 *
 * @template T - The type of items in the autocomplete dropdown.
 * @extends UseMultipleSelectionProps<T> - Props from the useMultipleSelection hook.
 *
 * @property {T[]} items - An array of items for the autocomplete dropdown.
 * @property {string} placeholder - The placeholder text for the input field.
 * @property {string} label - The label for the autocomplete component.
 * @property {string} [highlightItemBg] - Background color for the highlighted item in the dropdown.
 * @property {(item: T) => void} [onCreateItem] - Callback function when a new item is created.
 * @property {(items: T[], inputValue: string) => T[]} [optionFilterFunc] - Function to filter items based on input value.
 * @property {(item: T) => string | JSX.Element} [itemRenderer] - Custom renderer for each item in the dropdown.
 * @property {any} [labelStyleProps] - Additional style props for the label element.
 * @property {any} [inputStyleProps] - Additional style props for the input element.
 * @property {any} [toggleButtonStyleProps] - Additional style props for the toggle button (dropdown button).
 * @property {any} [tagStyleProps] - Additional style props for the selected tags.
 * @property {any} [listStyleProps] - Additional style props for the list (dropdown menu).
 * @property {() => any} [onClearAll] - Callback function when the "Clear All" button is clicked.
 * @property {any} [listItemStyleProps] - Additional style props for each item in the dropdown menu.
 * @property {(inputValue: string) => React.ReactNode} [emptyState] - Custom content to display when no items match the input.
 * @property {Omit<IconProps, 'name'> & { icon: IconProps['name'] | React.ComponentType }} [selectedIconProps] - Props for the icon indicating a selected item.
 * @property {React.ComponentType<IconProps>} [icon] - Custom icon component for the selected items.
 * @property {boolean} [hideToggleButton] - Whether to hide the toggle button (dropdown button).
 * @property {(value: string) => string | JSX.Element} [createItemRenderer] - Custom renderer for creating a new item.
 * @property {boolean} [disableCreateItem] - Whether to disable the creation of new items.
 * @property {(inputProps: any, toggleButtonProps: any) => JSX.Element} [renderCustomInput] - Custom renderer for the input field and toggle button.
 */
export interface CUIAutoCompleteProps<T extends Item> extends UseMultipleSelectionProps<T> {
    /**
     * An array of items for the autocomplete dropdown.
     *
     * @type {T[]}
     */
    items: T[];
    /**
     * Should the clear all button be enabled
     *
     * @type {boolean}
     * @default false
     */
    clearAll?: boolean;
    /**
     * Should Keyboard shortcuts be enabled
     *
     * @type {boolean}
     * @default true
     */
    keyboardShortcuts?: boolean;
    /**
     * The placeholder text for the input field.
     *
     * @type {string}
     */
    placeholder: string;
    /**
     * The label for the autocomplete component.
     *
     * @type {string}
     */
    label: string;
    /**
     * Background color for the highlighted item in the dropdown.
     *
     * @type {string|undefined}
     */
    highlightItemBg?: string;
    /**
     * Callback function when a new item is created.
     *
     * @type {(item: T) => void|undefined}
     */
    onCreateItem?: (item: T) => void;
    /**
     * Function to filter items based on the input value.
     *
     * @type {(items: T[], inputValue: string) => T[]|undefined}
     */
    optionFilterFunc?: (items: T[], inputValue: string) => T[];
    /**
     * Custom renderer for each item in the dropdown.
     *
     * @type {(item: T) => string | JSX.Element|undefined}
     */
    itemRenderer?: (item: T) => string | JSX.Element;
    /**
     * Additional style props for the label element.
     *
     * @type {React.HTMLAttributes<HTMLLabelElement>|undefined}
     */
    labelStyleProps?: React.HTMLAttributes<HTMLLabelElement>;
    /**
     * Additional style props for the input element.
     *
     * @type {React.InputHTMLAttributes<HTMLInputElement> & { size?: ResponsiveValue<string> } | undefined}
     */
    inputStyleProps?: React.InputHTMLAttributes<HTMLInputElement> & {
        size?: ResponsiveValue<string>;
    };
    /**
     * Additional style props for the toggle button (dropdown button).
     *
     * @type {React.ButtonHTMLAttributes<HTMLButtonElement>|undefined}
     */
    toggleButtonStyleProps?: React.ButtonHTMLAttributes<HTMLButtonElement>;
    /**
     * Additional style props for the selected tags.
     *
     * @type {React.HTMLAttributes<HTMLDivElement>|undefined|BoxProps}
     */
    tagStyleProps?: React.HTMLAttributes<HTMLDivElement> | BoxProps;
    /**
     * Additional style props for the list (dropdown menu).
     *
     * @type {React.HTMLAttributes<HTMLUListElement>|undefined}
     */
    listStyleProps?: React.HTMLAttributes<HTMLUListElement>;
    /**
     * Callback function when the "Clear All" button is clicked.
     *
     * @type {() => any|undefined}
     */
    onClearAll?: () => any;
    /**
     * Additional style props for each item in the dropdown menu.
     *
     * @type {React.HTMLAttributes<HTMLLIElement>|undefined}
     */
    listItemStyleProps?: React.HTMLAttributes<HTMLLIElement>;
    /**
     * Custom content to display when no items match the input.
     *
     * @type {(inputValue: string) => React.ReactNode|undefined}
     */
    emptyState?: (inputValue: string) => React.ReactNode;
    /**
     * Props for the icon indicating a selected item.
     *
     * @type {Omit<IconProps, 'name'> & { icon: IconProps['name'] | React.ComponentType }|undefined}
     */
    selectedIconProps?: Omit<IconProps, 'name'> & {
        icon: IconProps['name'] | React.ComponentType;
    };
    /**
     * Custom icon component for the selected items.
     *
     * @type {React.ComponentType<IconProps>|undefined}
     */
    icon?: React.ComponentType<IconProps>;
    /**
     * Whether to hide the toggle button (dropdown button).
     *
     * @type {boolean|undefined}
     */
    hideToggleButton?: boolean;
    /**
     * Custom renderer for creating a new item.
     *
     * @type {(value: string) => string | JSX.Element|undefined}
     */
    createItemRenderer?: (value: string) => string | JSX.Element;
    /**
     * Whether to disable the creation of new items.
     *
     * @type {boolean|undefined}
     */
    disableCreateItem?: boolean;
    /**
     * Custom renderer for the input field and toggle button.
     *
     * @type {(inputProps: React.InputHTMLAttributes<HTMLInputElement>, toggleButtonProps: React.ButtonHTMLAttributes<HTMLButtonElement>) => JSX.Element|undefined}
     */
    renderCustomInput?: (inputProps: React.InputHTMLAttributes<HTMLInputElement>, toggleButtonProps: React.ButtonHTMLAttributes<HTMLButtonElement>) => JSX.Element;
}
/**
 * Chakra UI Autocomplete Component.
 *
 * @component
 * @example
 * // Basic usage
 * <CUIAutoComplete
 *   items={[]}
 *   placeholder="Search..."
 *   hideToggleButton={true} // Hide the dropdown button
 *   label="Select or Create Items"
 *   onCreateItem={(item) => console.log('Created:', item)}
 *   onClearAll={() => console.log('Cleared all items')}
 *   clearAll={true} // Enable the clear all button
 * />
 *
 * @param {CUIAutoCompleteProps} props - Component properties.
 * @returns {React.ReactElement} - Autocomplete component.
 */
export declare const CUIAutoComplete: <T extends Item>(props: CUIAutoCompleteProps<T>) => React.ReactElement<CUIAutoCompleteProps<T>, string | ((props: any, deprecatedLegacyContext?: any) => React.ReactElement<any, any> | null) | (new (props: any, deprecatedLegacyContext?: any) => React.Component<any, any, any>)>;