@coreui/react-pro

import React, { HTMLAttributes, ReactNode } from 'react'; import { CFormControlWrapperProps } from '../form/CFormControlWrapper'; import type { Option, OptionsGroup, Search } from './types'; export interface CAutocompleteProps extends Omit<CFormControlWrapperProps, 'floatingClassName' | 'floatingLabel'>, Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'onInput'> { /** * Only allow selection of predefined options. * When `true`, users cannot enter custom values that are not in the options list. * When `false`, users can enter and select custom values. * * @default false */ allowOnlyDefinedOptions?: boolean; /** * A string of all className you want applied to the base component. * These classes will be merged with the default React autocomplete classes. */ className?: string; /** * Enables selection cleaner element. * When `true`, displays a clear button that allows users to reset the selection. * The cleaner button is only shown when there is a selection and the component is not disabled or read-only. * * @default false */ cleaner?: boolean; /** * Whether to clear the internal search state after selecting an option. * * When set to `true`, the internal search value used for filtering options is cleared * after a selection is made. This affects only the component's internal logic. * * Note: This does **not** clear the visible input field if the component is using external search * or is controlled via the `searchValue` prop. In such cases, clearing must be handled externally. * * @default true */ clearSearchOnSelect?: boolean; /** * Specifies the DOM element where the dropdown should be rendered when using portal mode. * Can be a DOM element reference, DocumentFragment, function that returns an element or null, * or null (renders to document body). Works in conjunction with the `portal` prop to control * where the portal content is mounted in the DOM tree. */ container?: DocumentFragment | Element | (() => DocumentFragment | Element | null) | null; /** * Toggle the disabled state for the component. * When `true`, the React.js autocomplete is non-interactive and appears visually disabled. * Users cannot type, select options, or trigger the dropdown. */ disabled?: boolean; /** * Highlight options that match the search criteria. * When `true`, matching portions of option labels are visually highlighted * based on the current search input value. * * @default false */ highlightOptionsOnSearch?: boolean; /** * Set the id attribute for the native input element. * This id is used for accessibility purposes and form associations. * If not provided, a unique id may be generated automatically. */ id?: string; /** * Show dropdown indicator/arrow button. * When `true`, displays a dropdown arrow button that can be clicked * to manually show or hide the options dropdown. */ indicator?: boolean; /** * When set, the options list will have a loading style: loading spinner and reduced opacity. * Use this to indicate that options are being fetched asynchronously. * The dropdown remains functional but shows visual loading indicators. */ loading?: boolean; /** * The name attribute for the input element. * Used for form submission and identification in form data. * Important for proper form handling and accessibility. */ name?: string; /** * Execute a function when a user changes the selected option. * Called with the selected option object or `undefined` when cleared. * This is the primary callback for handling selection changes. * * @param option - The selected option object, or `undefined` if cleared */ onChange?: (option: Option | null) => void; /** * Execute a function when the filter/search value changes. * Called whenever the user types in the search input. * Useful for implementing external search functionality or analytics. * * @param value - The current search input value */ onInput?: (value: string) => void; /** * The callback is fired when the dropdown requests to be hidden. * Called when the dropdown closes due to user interaction, clicks outside, * escape key, or programmatic changes. */ onHide?: () => void; /** * The callback is fired when the dropdown requests to be shown. * Called when the dropdown opens due to user interaction, focus, * or programmatic changes. */ onShow?: () => void; /** * List of option elements. * Can contain Option objects, OptionsGroup objects, or plain strings. * Plain strings are converted to simple Option objects internally. * This is a required prop - the React autocomplete needs options to function. */ options: (Option | OptionsGroup | string)[]; /** * Sets maxHeight of options list. * Controls the maximum height of the dropdown options container. * Can be a number (pixels) or a CSS length string (e.g., '200px', '10rem'). * When content exceeds this height, a scrollbar will appear. * * @default 'auto' */ optionsMaxHeight?: number | string; /** * Custom template for rendering individual options. * Allows complete customization of how each option appears in the dropdown. * The function receives an Option object and should return a ReactNode. * * @param option - The option object to render * @returns ReactNode to display for this option */ optionsTemplate?: (option: Option) => ReactNode; /** * Custom template for rendering option groups. * Allows customization of how option group headers appear in the dropdown. * The function receives an OptionsGroup object and should return a ReactNode. * * @param option - The options group object to render * @returns ReactNode to display for this group header */ optionsGroupsTemplate?: (option: OptionsGroup) => ReactNode; /** * Specifies a short hint that is visible in the search input. * Displayed when the input is empty to guide user interaction. * Standard HTML input placeholder behavior. */ placeholder?: string; /** * Renders the autocomplete dropdown in a React portal, allowing it to break out of its * parent container's styling constraints (like overflow, z-index, or positioning). * When enabled, the dropdown is rendered at the document root level, ensuring it appears * above other page elements and isn't clipped by parent containers. * * @default false */ portal?: boolean; /** * Toggle the readonly state for the component. * When `true`, users can view and interact with the dropdown but cannot * type in the search input or modify the selection through typing. * Selection via clicking options may still be possible. */ readOnly?: boolean; /** * When it is present, it indicates that the user must choose a value before submitting the form. * Adds HTML5 form validation requirement. The form will not submit * until a valid selection is made. */ required?: boolean; /** * Determines whether the selected options should be cleared when the options list is updated. * When `true`, any previously selected options will be reset whenever the options * list undergoes a change. This ensures that outdated selections are not retained * when new options are provided. * * @default false */ resetSelectionOnOptionsChange?: boolean; /** * Enables and configures search functionality. * - `'external'`: Search is handled externally, filtering is not applied internally * - `'global'`: Enables global keyboard search when dropdown is closed * - Object with `external` and `global` boolean properties for fine-grained control */ search?: Search; /** * Sets the label for no results when filtering. * - `false`: Don't show any message when no results found * - `true`: Show default "No results found" message * - `string`: Show custom text message * - `ReactNode`: Show custom component/element * * @default false */ searchNoResultsLabel?: boolean | string | ReactNode; /** * Show hint options based on the current input value. * When `true`, displays a preview/hint of the first matching option * as semi-transparent text in the input field, similar to browser autocomplete. * * @default false */ showHints?: boolean; /** * Size the component small or large. * - `'sm'`: Small size variant * - `'lg'`: Large size variant * - `undefined`: Default/medium size */ size?: 'sm' | 'lg'; /** * Sets the initially selected value for the React.js autocomplete component. * Can be a string (matched against option labels) or number (matched against option values). * The component will attempt to find and select the matching option on mount. */ value?: number | string; /** * Enable virtual scroller for the options list. * When `true`, only visible options are rendered in the DOM for better performance * with large option lists. Works in conjunction with `visibleItems` prop. * * @default false */ virtualScroller?: boolean; /** * Toggle the visibility of autocomplete dropdown. * Controls whether the dropdown is initially visible. * The dropdown visibility can still be toggled through user interaction. */ visible?: boolean; /** * Amount of visible items when virtualScroller is enabled. * Determines how many option items are rendered at once when virtual scrolling is active. * Higher values show more items but use more memory. Lower values improve performance. * * @default 10 */ visibleItems?: number; } export declare const CAutocomplete: React.ForwardRefExoticComponent<CAutocompleteProps & React.RefAttributes<HTMLDivElement>>;