@carbon/utilities/types/overflowHandler/overflowHandler.d.ts

Utilities and helpers to drive consistency across software products using the Carbon Design System

/**
 * Copyright IBM Corp. 2025
 *
 * This source code is licensed under the Apache-2.0 license found in the
 * LICENSE file in the root directory of this source tree.
 */
/**
 * Calculates the size (width or height) of a given HTML element.
 *
 * This function performs an expensive calculation by temporarily changing the
 * display style of the element if it is not currently visible. It then uses
 * `getBoundingClientRect` to retrieve the size of the element.
 *
 * @param el - The HTML element whose size is to be calculated.
 * @param dimension - The dimension to measure ('width' or 'height').
 * @returns The size of the element in pixels. Returns 0 if the element is not provided.
 */
export declare function getSize(el: HTMLElement, dimension: 'width' | 'height'): number;
/**
 * Options for updating the overflow handler.
 * Determines which items should be visible and which should be hidden
 * based on the container size, item sizes, and other constraints.
 */
export interface UpdateOverflowHandlerOptions {
    /** The container element that holds the items. */
    container: HTMLElement;
    /** An array of item elements to be managed for overflow. */
    items: HTMLElement[];
    /** An element that represents the offset, which can be shown or hidden based on overflow. Identified by `data-offset` attribute. */
    offset: HTMLElement;
    /** An array of sizes corresponding to each item in the `items` array. */
    sizes: number[];
    /** An array of sizes corresponding to each item in the fixed items array. */
    fixedSizes: number[];
    /** The size of the offset element. */
    offsetSize: number;
    /** The maximum number of items that can be visible at once. If undefined, all items can be visible. */
    maxVisibleItems?: number;
    /** The dimension to consider for overflow, either 'width' or 'height'. */
    dimension: 'width' | 'height';
    /** A callback function that is called when the visible or hidden items change. */
    onChange: (visibleItems: HTMLElement[], hiddenItems: HTMLElement[]) => void;
    /** An array of previously hidden items to compare against the new hidden items. */
    previousHiddenItems?: HTMLElement[];
}
/**
 * Updates the overflow handler by determining which items should be visible and which should be hidden.
 *
 * @param options - Configuration options for updating the overflow handler.
 * @returns An array of hidden items after the update.
 */
export declare function updateOverflowHandler({ container, items, offset, sizes, fixedSizes, offsetSize, maxVisibleItems, dimension, onChange, previousHiddenItems, }: UpdateOverflowHandlerOptions): HTMLElement[];
/**
 * Options for initializing an overflow handler.
 */
export interface OverflowHandlerOptions {
    /**
     * The container element that holds the items. along with offset item
     */
    container: HTMLElement;
    /**
     * Maximum number of visible items. If provided, only this number of items will be shown.
     */
    maxVisibleItems?: number;
    /**
     * Callback function invoked when the visible and hidden items change.
     * @param visibleItems - The array of items that are currently visible.
     * @param hiddenItems - The array of items that are currently hidden.
     */
    onChange: (visibleItems: HTMLElement[], hiddenItems: HTMLElement[]) => void;
    /**
     * The dimension to consider for overflow calculations. Defaults to 'width'.
     */
    dimension?: 'width' | 'height';
}
/**
 * Represents an instance of an overflow handler.
 */
export interface OverflowHandler {
    /**
     * Disconnects the overflow handler, cleaning up any event listeners or resources.
     */
    disconnect: () => void;
}
export declare function createOverflowHandler({ container, maxVisibleItems, onChange, dimension, }: OverflowHandlerOptions): OverflowHandler;