@coreui/react-pro/dist/esm/components/focus-trap/CFocusTrap.d.ts

UI Components Library for React.js

import React, { FC, ReactElement } from 'react';
export interface CFocusTrapProps {
    /**
     * Controls whether the focus trap is active or inactive.
     * When `true`, focus will be trapped within the child element.
     * When `false`, normal focus behavior is restored.
     *
     * @default true
     */
    active?: boolean;
    /**
     * Additional container elements to include in the focus trap.
     * Useful for floating elements like tooltips or popovers that are
     * rendered outside the main container but should be part of the trap.
     */
    additionalContainer?: React.RefObject<HTMLElement | null>;
    /**
     * Single React element that renders a DOM node and forwards refs properly.
     * The focus trap will be applied to this element and all its focusable descendants.
     *
     * Requirements:
     * - Must be a single ReactElement (not an array or fragment)
     * - Must forward the ref to a DOM element
     * - Should contain focusable elements for proper trap behavior
     */
    children: ReactElement;
    /**
     * Controls whether to focus the first selectable element or the container itself.
     * When `true`, focuses the first tabbable element within the container.
     * When `false`, focuses the container element directly.
     *
     * This is useful for containers that should receive focus themselves,
     * such as scrollable regions or custom interactive components.
     *
     * @default false
     */
    focusFirstElement?: boolean;
    /**
     * Callback function invoked when the focus trap becomes active.
     * Useful for triggering additional accessibility announcements or analytics.
     */
    onActivate?: () => void;
    /**
     * Callback function invoked when the focus trap is deactivated.
     * Can be used for cleanup, analytics, or triggering state changes.
     */
    onDeactivate?: () => void;
    /**
     * Automatically restores focus to the previously focused element when the trap is deactivated.
     * This is crucial for accessibility as it maintains the user's place in the document
     * when returning from modal dialogs or overlay components.
     *
     * Recommended to be `true` for modal dialogs and popover components.
     *
     * @default true
     */
    restoreFocus?: boolean;
}
export declare const CFocusTrap: FC<CFocusTrapProps>;