@progress/kendo-react-popup/index.d.ts

React Popup positions a piece of content next to a specific anchor component. KendoReact Popup package

/**
 * @license
 *-------------------------------------------------------------------------------------------
 * Copyright © 2025 Progress Software Corporation. All rights reserved.
 * Licensed under commercial license. See LICENSE.md in the package root for more information
 *-------------------------------------------------------------------------------------------
 */
import { AlignStrategy } from '@progress/kendo-popup-common';
import { CollisionType as CollisionType_2 } from '@progress/kendo-popup-common';
import { MarginSettings } from '@progress/kendo-popup-common';
import { OffsetPosition } from '@progress/kendo-popup-common';
import { PopupClassStructure } from '@progress/kendo-react-common';
import { PopupSettings } from '@progress/kendo-popup-common';
import { PositionMode as PositionMode_2 } from '@progress/kendo-popup-common';
import * as React_2 from 'react';

/**
 * Defines the horizontal and vertical aligning point of the Popup.
 */
export declare interface Align extends AlignStrategy {
    /**
     * Defines the possible horizontal point values that are relative to the anchor or the Popup.
     *
     * The available options are:
     * - `left`—Uses the leftmost point of the anchor element.
     * - `center`—Uses the center point of the anchor element.
     * - `right`—Uses the rightmost point of the anchor element.
     */
    horizontal: 'left' | 'center' | 'right';
    /**
     * Defines the possible vertical point values that are relative to the anchor or the Popup.
     *
     * The available options are:
     * - `top`—Uses the top point of the anchor element.
     * - `center`—Uses the center point of the anchor element.
     * - `bottom`—Uses the bottom point of the anchor element.
     */
    vertical: 'top' | 'center' | 'bottom';
}

/**
 * The available animation types for the Popup component.
 *
 * Possible values: 'slide', 'zoom', 'push', 'expand', 'fade'.
 *
 * @example
 * <Popup animation={{ type: 'slide' }} />
 */
declare const animationTypes: {
    readonly slide: "slide";
    readonly zoom: "zoom";
    readonly push: "push";
    readonly expand: "expand";
    readonly fade: "fade";
};

/**
 * Defines the horizontal and vertical collision behavior of the Popup.
 */
export declare interface Collision {
    /**
     * Defines the horizontal collision behavior of the Popup.
     */
    horizontal: CollisionType;
    /**
     * Defines the vertical collision behavior of the Popup.
     */
    vertical: CollisionType;
}

/**
 * Defines the possible collision behavior when the Popup is not fully visible.
 *
 * The available options are:
 * - `fit`&mdash;Moves the Popup horizontally until it is fully displayed in the viewport.
 * - `flip`&mdash;Flips the Popup position based on the origin and the position properties.
 * - `none`&mdash;The Popup is rendered at its original position.
 */
export declare type CollisionType = CollisionType_2;

/**
 * Defines the expand animation settings for the Popup component.
 *
 * Use this to configure expand type and direction
 *
 * @example
 * <Popup animation={{ type: 'expand', direction: 'vertical' }} />
 */
export declare interface ExpandPopupAnimation {
    /**
     * The type of the animation. Must be 'expand'.
     */
    type: typeof animationTypes.expand;
    /**
     * The direction of the expand animation. Possible values: 'horizontal', 'vertical'.
     */
    direction: PopupExpandDirection;
}

/**
 * Defines the fade animation settings for the Popup component.
 *
 * Use this to configure fade type. Direction is always 'none'.
 *
 * @example
 * <Popup animation={{ type: 'fade' }} />
 */
export declare interface FadePopupAnimation {
    /**
     * The type of the animation. Must be 'fade'.
     */
    type: typeof animationTypes.fade;
    /**
     * @hidden
     */
    direction?: PopupNoDirection;
}

/**
 * Defines the horizontal and the vertical margin offset of the component.
 */
export declare interface Margin extends MarginSettings {
    /**
     * Defines the possible horizontal margin value.
     */
    horizontal: number;
    /**
     * Defines the possible vertical margin value.
     */
    vertical: number;
}

/**
 * Represents the object of the `MouseDownOutside` Popup event.
 */
export declare interface MouseDownOutsideEvent {
    /**
     * An event target.
     */
    target: PopupHandle;
    /**
     * The event object.
     */
    event: MouseEvent;
    /**
     * The state of the Popup.
     */
    state: PopupState;
    /**
     * Indicates if the MouseDown event is triggered over the anchor of the Popup.
     */
    isAnchorClicked: boolean;
}

/**
 * The offset position of the Popup.
 */
export declare interface Offset extends OffsetPosition {
    /**
     * Defines the top position of the Popup.
     */
    top: number;
    /**
     * Defines the left position of the Popup.
     */
    left: number;
}

/**
 * The KendoReact Popup component.
 */
export declare const Popup: React_2.ForwardRefExoticComponent<PopupProps & React_2.RefAttributes<PopupHandle | null>>;

/**
 * The animation settings for the Popup component
 */
export declare type PopupAnimation = PopupAnimationBase & (FadePopupAnimation | SlidePopupAnimation | ZoomPopupAnimation | PushPopupAnimation | ExpandPopupAnimation);

/**
 * Defines the base animation settings for the Popup component.
 *
 * Includes duration properties for opening and closing animations
 *
 * @example
 * <Popup animation={{ openDuration: 500, closeDuration: 200 }} />
 */
export declare interface PopupAnimationBase {
    /**
     * The duration of the opening animation in milliseconds. Defaults to `300ms`.
     */
    openDuration?: number;
    /**
     * The duration of the closing animation in milliseconds. Defaults to `300ms`.
     */
    closeDuration?: number;
}

/**
 * Represents all possible direction values for Popup animations.
 *
 * Includes directions for slide, zoom, push, expand, and fade animations.
 * Useful for type-safe direction assignment in animation settings.
 *
 * Possible values: 'left', 'right', 'up', 'down', 'in', 'out', 'horizontal', 'vertical', 'none'.
 */
export declare type PopupAnimationDirection = NonNullable<FadePopupAnimation['direction'] | SlidePopupAnimation['direction'] | ZoomPopupAnimation['direction'] | PushPopupAnimation['direction'] | ExpandPopupAnimation['direction']>;

/**
 * The type representing all possible animation type values.
 *
 * Possible values: 'slide', 'zoom', 'push', 'expand', 'fade'
 *
 * @example
 * <Popup animation={{ type: 'fade' }} />
 */
export declare type PopupAnimationType = (typeof animationTypes)[keyof typeof animationTypes];

/**
 * The possible base directions for slide and push animations.
 *
 * Possible values: 'left', 'right', 'up', 'down'.
 *
 * @example
 * <Popup animation={{ direction: 'left' }} />
 */
export declare type PopupBaseDirections = 'left' | 'right' | 'up' | 'down';

/**
 * Represents the object of the `Close` Popup event.
 */
export declare interface PopupCloseEvent {
    /**
     * An event target.
     */
    target: PopupHandle;
}

/**
 * The possible directions for expand animations.
 *
 * Possible values: 'horizontal', 'vertical'.
 *
 * @example
 * <Popup animation={{ type: 'expand', direction: 'vertical' }} />
 */
export declare type PopupExpandDirection = 'horizontal' | 'vertical';

/**
 * The KendoReact PopupHandle component.
 */
export declare interface PopupHandle {
    /**
     * Represents the Popup DOM element.
     */
    element: any;
    /**
     * The props of the PopupHandle component.
     */
    props: PopupProps;
}

/**
 * Represents no direction for fade animation.
 *
 * Possible value: 'none'.
 *
 * @example
 * <Popup animation={{ type: 'fade', direction: 'none' }} />
 */
export declare type PopupNoDirection = 'none';

/**
 * Represents the object of the `Open` Popup event.
 */
export declare interface PopupOpenEvent {
    /**
     * An event target.
     */
    target: PopupHandle;
}

/**
 * Represents the props of the [KendoReact Popup component]({% slug overview_popup %}).
 */
export declare interface PopupProps extends PopupSettings {
    /**
     * Controls the Popup animation ([see example]({% slug animations_popup %})). By default, the opening and closing animations are enabled.
     *
     * @default true
     *
     * @example
     * ```jsx
     * <Popup animate={false} />
     * ```
     */
    animate?: boolean | PopupAnimation;
    /**
     * Specifies the element which will be used as an anchor ([see example]({% slug alignmentpositioning_popup %})). The Popup opens next to that element.
     *
     * @example
     * ```jsx
     * <Popup anchor={document.getElementById('anchorElement')} />
     * ```
     */
    anchor?: HTMLElement | null;
    /**
     * Defines the container to which the Popup will be appended. Defaults to [`body`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body).
     * * If set to `null` the Popup will be rendered without React Portal.
     *
     * @default document.body
     *
     * @example
     * ```jsx
     * <Popup appendTo={document.getElementById('container')} />
     * ```
     */
    appendTo?: HTMLElement | null;
    /**
     * Specifies the pivot point of the anchor ([see example]({% slug alignmentpositioning_popup %})).
     *
     * @example
     * ```jsx
     * <Popup anchorAlign={{ horizontal: 'left', vertical: 'top' }} />
     * ```
     */
    anchorAlign?: Align;
    /**
     * Configures the collision behavior of the Popup ([see example]({% slug viewportboundarydetection_popup %})).
     *
     * @example
     * ```jsx
     * <Popup collision={{ horizontal: 'fit', vertical: 'flip' }} />
     * ```
     */
    collision?: Collision;
    /**
     * Configures the margin value that will be added to the popup dimensions
     * in pixels and leaves a blank space between the popup and the anchor.
     *
     * @example
     * ```jsx
     * <Popup margin={{ horizontal: 10, vertical: 10 }} />
     * ```
     */
    margin?: Margin;
    /**
     * Specifies the position mode of the component. By default, the Popup uses absolute positioning.
     * To make the Popup acquire fixed positioning, set this option to `fixed`.
     *
     * @default "absolute"
     *
     * @example
     * ```jsx
     * <Popup positionMode="fixed" />
     * ```
     */
    positionMode?: PositionMode;
    /**
     * Used to set the document scale when using a [scale transform](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/scale).
     *
     * The document or container scale is required to compute the popup position correctly. Detecting the scale is not reliable and must be set by providing a value for SCALE.
     *
     * > Using this token is not necessary for user-applied browser zoom.
     *
     * @example
     * ```jsx
     * <Popup scale={1.5} />
     * ```
     */
    scale?: number;
    /**
     * Specifies the pivot point of the Popup ([see example]({% slug alignmentpositioning_popup %})).
     *
     * @example
     * ```jsx
     * <Popup popupAlign={{ horizontal: 'center', vertical: 'bottom' }} />
     * ```
     */
    popupAlign?: Align;
    /**
     * Specifies the absolute position of the element ([see example]({% slug alignmentpositioning_popup %})). The Popup opens next to that point. The pivot point of the Popup is defined by the `popupAlign` configuration option. The boundary detection is applied by using the window viewport.
     *
     * @example
     * ```jsx
     * <Popup offset={{ left: 100, top: 200 }} />
     * ```
     */
    offset?: Offset;
    /**
     * Specifies a list of CSS classes that will be added to the internal animated element ([see example]({% slug appearance_popup %})).
     *
     * @example
     * ```jsx
     * <Popup popupClass="custom-popup-class" />
     * ```
     */
    popupClass?: string | Array<string> | {
        [key: string]: boolean;
    };
    /**
     * Specifies a list of CSS classes that will be added to the Popup element.
     *
     * @example
     * ```jsx
     * <Popup className="custom-class" />
     * ```
     */
    className?: string | Array<string>;
    /**
     * Specifies the id that will be added to the Popup element.
     *
     * @example
     * ```jsx
     * <Popup id="popup-id" />
     * ```
     */
    id?: string;
    /**
     * Represents the styles that are applied to the Popup.
     *
     * @example
     * ```jsx
     * <Popup style={{ width: '200px', height: '100px' }} />
     * ```
     */
    style?: React.CSSProperties;
    /**
     * Fires after the Popup is opened and the opening animation ends.
     *
     * @example
     * ```jsx
     * <Popup onOpen={(event) => console.log('Popup opened')} />
     * ```
     */
    onOpen?: (event: PopupOpenEvent) => void;
    /**
     * Fires after the Popup is closed.
     *
     * @example
     * ```jsx
     * <Popup onClose={(event) => console.log('Popup closed')} />
     * ```
     */
    onClose?: (event: PopupCloseEvent) => void;
    /**
     * Fires after the Popup position is set.
     *
     * @example
     * ```jsx
     * <Popup onPosition={(event) => console.log('Popup positioned')} />
     * ```
     */
    onPosition?: (event: PositionEvent) => void;
    /**
     * Fires when the mousedown event is triggered outside the Popup.
     *
     * @example
     * ```jsx
     * <Popup onMouseDownOutside={(event) => console.log('onMouseDownOutside')} />
     * ```
     */
    onMouseDownOutside?: (event: MouseDownOutsideEvent) => void;
    /**
     * Controls the Popup visibility ([see example]({% slug hidden_popup %})). Defaults to `false`.
     *
     * @default false
     *
     * @example
     * ```jsx
     * <Popup show={true} />
     * ```
     */
    show?: boolean;
    /**
     * @hidden
     *
     * If contentKey has changed, the popup will recalculate its position.
     */
    contentKey?: any;
    /**
     * @hidden
     */
    children?: React.ReactNode;
    /**
     * @hidden
     */
    useBaseStyles?: boolean;
    /**
     * @hidden
     */
    role?: string;
    /**
     * @hidden
     */
    onKeyDown?: (event: React.KeyboardEvent) => void;
    /**
     * @hidden
     */
    unstyled?: PopupClassStructure;
}

/**
 * The PopupPropsContext. It allows to configure the Popup props from a wrapper component.
 *
 * @example
 * ```jsx-no-run
 *  <PopupPropsContext.Provider value={props => ({ ...props, appendTo: document.querySelector('myPopupsContainer') })}>
 *      <DropDownList />
 *      <Editor />
 *  </PopupPropsContext.Provider>
 * ```
 */
export declare const PopupPropsContext: React_2.Context<(props: PopupProps) => PopupProps>;

/**
 * @hidden
 */
declare interface PopupState {
    current: Status;
    previous: Status;
    props: {
        show?: boolean;
        anchor?: HTMLElement | null;
        anchorAlign?: Align;
        appendTo?: HTMLElement | null;
        collision?: Collision;
        popupAlign?: Align;
        className?: string | string[] | {
            [key: string]: boolean;
        };
        popupClass?: string | string[] | {
            [key: string]: boolean;
        };
        style?: React_2.CSSProperties;
        offset?: Offset;
        contentKey?: any;
    };
}

/**
 * The possible directions for zoom animations.
 *
 * Possible values: 'in', 'out'.
 *
 * @example
 * <Popup animation={{ type: 'zoom', direction: 'in' }} />
 */
export declare type PopupZoomDirections = 'in' | 'out';

/**
 * Represents the object of the `Position` Popup event.
 */
export declare interface PositionEvent {
    /**
     * An event target.
     */
    target: PopupHandle;
    /**
     * Indicates if the position is fitted.
     */
    fitted: boolean;
    /**
     * Indicates if the position is flipped.
     */
    flipped: boolean;
}

/**
 * The type which defines all possible position modes of the Popup.
 */
export declare type PositionMode = PositionMode_2;

/**
 * Defines the push animation settings for the Popup component.
 *
 * Use this to configure push type and direction
 *
 * @example
 * <Popup animation={{ type: 'push', direction: 'down' }} />
 */
export declare interface PushPopupAnimation {
    /**
     * The type of the animation. Must be 'push'.
     */
    type: typeof animationTypes.push;
    /**
     * The direction of the push animation. Possible values: 'left', 'right', 'up', 'down'.
     */
    direction: PopupBaseDirections;
}

/**
 * Defines the slide animation settings for the Popup component.
 *
 * Use this to configure slide type and direction
 *
 * @example
 * <Popup animation={{ type: 'slide', direction: 'left' }} />
 */
export declare interface SlidePopupAnimation {
    /**
     * The type of the animation. Default is 'slide'.
     */
    type?: typeof animationTypes.slide;
    /**
     * The direction of the slide animation. Possible values: 'left', 'right', 'up', 'down'.
     */
    direction?: PopupBaseDirections;
}

declare enum Status {
    hiding = "hiding",
    hidden = "hidden",
    showing = "showing",
    shown = "shown",
    reposition = "reposition"
}

/**
 * Defines the zoom animation settings for the Popup component.
 *
 * Use this to configure zoom type and direction
 *
 * @example
 * <Popup animation={{ type: 'zoom', direction: 'in' }} />
 */
export declare interface ZoomPopupAnimation {
    /**
     * The type of the animation. Must be 'zoom'.
     */
    type: typeof animationTypes.zoom;
    /**
     * The direction of the zoom animation. Possible values: 'in', 'out'.
     */
    direction: PopupZoomDirections;
}

export { }