@progress/kendo-react-tooltip
Version:
React Tooltips library represents popups with information that is related to a UI element. KendoReact Tooltips package
810 lines (784 loc) • 23.1 kB
TypeScript
/**
* @license
*-------------------------------------------------------------------------------------------
* Copyright © 2025 Progress Software Corporation. All rights reserved.
* Licensed under commercial license. See LICENSE.md in the package root for more information
*-------------------------------------------------------------------------------------------
*/
import { BaseEvent } from '@progress/kendo-react-common';
import { CollisionType } from '@progress/kendo-react-popup';
import { default as default_2 } from 'prop-types';
import { JSX } from 'react/jsx-runtime';
import { Margin } from '@progress/kendo-react-popup';
import { Offset } from '@progress/kendo-react-popup';
import { PopupAnimation } from '@progress/kendo-react-popup';
import { PositionMode } from '@progress/kendo-react-popup';
import * as React_2 from 'react';
import { ZIndexContext } from '@progress/kendo-react-common';
import { ZIndexContextType } from '@progress/kendo-react-common';
/**
* Represents the Popover component.
*/
export declare const Popover: React_2.ForwardRefExoticComponent<PopoverProps & React_2.RefAttributes<PopoverHandle | null>>;
/**
* Represents the PopoverActionsBar component.
*/
export declare const PopoverActionsBar: React_2.ForwardRefExoticComponent<PopoverActionsBarProps & React_2.RefAttributes<PopoverActionsBarHandle | null>>;
/**
* Represents the Object which is passed to the [`ref`](https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom) callback of the PopoverActionBar component.
*/
export declare interface PopoverActionsBarHandle {
/**
* The props of the PopoverActionsBar.
*/
props: PopoverActionsBarProps;
/**
* The current element or `null` if there is none.
*/
element: HTMLDivElement | null;
}
/**
* Represents the props of the [KendoReact PopoverActionsBar]({% slug api_tooltip_popoveractionsbar %}) component.
*/
export declare interface PopoverActionsBarProps {
/**
* Sets the horizontal alignment of the PopoverActionsBar buttons.
*
* The possible values are:
* * `start`
* * `center`
* * `end`
* * `stretched` (default)
*/
alignment?: string;
/**
* Sets the orientation of the PopoverActionsBar buttons.
*
* The possible values are:
* * `horizontal` (default)
* * `vertical`
*/
orientation?: string;
/**
* @hidden
*/
children?: React.ReactNode;
}
/**
* The animation settings of the Popover.
*/
export declare interface PopoverAnimation extends PopupAnimation {
}
/**
* Represents the object of the `Close` Popover event.
*/
export declare interface PopoverCloseEvent {
/**
* An event target.
*/
target: PopoverHandle;
}
/**
* Defines the horizontal and vertical collision behavior of the Popover.
*/
export declare interface PopoverCollision {
/**
* Defines the horizontal collision behavior of the Popover.
*/
horizontal: PopoverCollisionType;
/**
* Defines the vertical collision behavior of the Popover.
*/
vertical: PopoverCollisionType;
}
/**
* Defines the possible collision behavior when the Popover is not fully visible.
*
* The available options are:
* - `fit`—Moves the Popover horizontally until it is fully displayed in the viewport.
* - `flip`—Flips the Popover position based on the origin and the position properties.
* - `none`—The Popover is rendered at its original position. Usable when the Popover is focused on open and the page is scrolled to it.
*/
export declare type PopoverCollisionType = CollisionType;
/**
* Represents the Object which is passed to the [`ref`](https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom) callback of the Popover component.
*/
export declare interface PopoverHandle {
/**
* The props of the Popover.
*/
props: PopoverProps;
}
/**
* Represents the object of the `KeyDown` Popover event.
*/
export declare interface PopoverKeyDownEvent {
/**
* An event target.
*/
target: PopoverHandle;
/**
* A boolean value that indicates whether the Popover is visible.
*/
show?: boolean;
}
/**
* Defines the horizontal and the vertical margin offset of the component.
*/
export declare interface PopoverMargin extends Margin {
/**
* Defines the possible horizontal margin value.
*/
horizontal: number;
/**
* Defines the possible vertical margin value.
*/
vertical: number;
}
/**
* The offset position of the Popover.
*/
export declare interface PopoverOffset extends Offset {
/**
* Defines the top position of the Popover.
*/
top: number;
/**
* Defines the left position of the Popover.
*/
left: number;
}
/**
* Represents the object of the `Open` Popover event.
*/
export declare interface PopoverOpenEvent {
/**
* An event target.
*/
target: PopoverHandle;
}
/**
* The position of the Popover.
* The available options are:
* - `top`
* - `left`
* - `bottom`
* - `right`
*/
export declare type PopoverPosition = 'top' | 'left' | 'bottom' | 'right';
/**
* Represents the object of the `Position` Popover event.
*/
export declare interface PopoverPositionEvent {
/**
* An event target.
*/
target: PopoverHandle;
/**
* 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 Popover.
*/
export declare type PopoverPositionMode = PositionMode;
export declare interface PopoverProps {
/**
* Specifies the title of the Popover component.
* Can be a string or JSX content.
*
* @example
* ```jsx
* <Popover title="Popover Title" />
* ```
*/
title?: React.ReactNode;
/**
* Specifies the position of the Popover relative to the anchor or offset.
* Accepts predefined position values.
*
* @example
* ```jsx
* <Popover position="top" />
* ```
*/
position?: PopoverPosition;
/**
* Controls the visibility of the Popover callout (arrow).
* If set to `false`, the callout will not be rendered.
*
* @example
* ```jsx
* <Popover callout={false} />
* ```
*/
callout?: boolean;
/**
* Configures the animation behavior of the Popover.
* Accepts a boolean or a configuration object.
*
* @example
* ```jsx
* <Popover animate={true} />
* ```
*/
animate?: boolean | PopoverAnimation;
/**
* Specifies the element to be used as the anchor for the Popover.
* The Popover opens relative to this element.
*
* @example
* ```jsx
* <Popover anchor={document.getElementById('anchor')} />
* ```
*/
anchor?: HTMLElement | null;
/**
* Defines the container to which the Popover will be appended.
* Defaults to [`body`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body).
* If set to `null`, the Popover will not use React Portal.
*
* @example
* ```jsx
* <Popover appendTo={document.getElementById('container')} />
* ```
*/
appendTo?: HTMLElement | null;
/**
* Configures the collision behavior of the Popover.
* Determines how the Popover adjusts its position when it overflows the viewport.
*
* @example
* ```jsx
* <Popover collision={{ horizontal: 'fit', vertical: 'flip' }} />
* ```
*/
collision?: PopoverCollision;
/**
* Specifies the margin in pixels between the Popover and the anchor element.
* Automatically set based on the `position` property if not specified.
*
* @example
* ```jsx
* <Popover margin={{ top: 10, left: 5 }} />
* ```
*/
margin?: PopoverMargin;
/**
* Specifies the positioning mode of the Popover.
* Defaults to `fixed`. Use `absolute` for mobile browser support with zoom.
*
* @example
* ```jsx
* <Popover positionMode="absolute" />
* ```
*/
positionMode?: PopoverPositionMode;
/**
* Specifies the document scale when using a [scale transform](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/scale).
* Required for accurate positioning when scaling is applied.
*
* @example
* ```jsx
* <Popover scale={1.5} />
* ```
*/
scale?: number;
/**
* Specifies the absolute position of the Popover.
* The Popover opens relative to this point.
*
* @example
* ```jsx
* <Popover offset={{ top: 100, left: 200 }} />
* ```
*/
offset?: PopoverOffset;
/**
* Specifies additional CSS classes for the animated Popover element.
*
* @example
* ```jsx
* <Popover popoverClass="custom-popover-class" />
* ```
*/
popoverClass?: string | Array<string> | {
[key: string]: boolean;
};
/**
* Specifies additional CSS classes for the Popover element.
*
* @example
* ```jsx
* <Popover className="custom-class" />
* ```
*/
className?: string | Array<string>;
/**
* Specifies the `id` attribute for the Popover element.
*
* @example
* ```jsx
* <Popover id="popover-id" />
* ```
*/
id?: string;
/**
* Specifies the styles applied to the Popover element.
*
* @example
* ```jsx
* <Popover style={{ backgroundColor: 'blue' }} />
* ```
*/
style?: React.CSSProperties;
/**
* Specifies the styles applied to the content element of the Popover.
*
* @example
* ```jsx
* <Popover contentStyle={{ padding: '10px' }} />
* ```
*/
contentStyle?: React.CSSProperties;
/**
* Controls the visibility of the Popover.
* Defaults to `false`.
*
* @example
* ```jsx
* <Popover show={true} />
* ```
*/
show?: boolean;
/**
* Fires after the Popover is opened and the opening animation ends.
* Provides the event details.
*
* @example
* ```jsx
* <Popover onOpen={(event) => console.log('Popover opened', event)} />
* ```
*/
onOpen?: (event: PopoverOpenEvent) => void;
/**
* Fires after the Popover is closed.
* Provides the event details.
*
* @example
* ```jsx
* <Popover onClose={(event) => console.log('Popover closed', event)} />
* ```
*/
onClose?: (event: PopoverCloseEvent) => void;
/**
* Fires after the Popover position is calculated and set.
* Provides the event details.
*
* @example
* ```jsx
* <Popover onPosition={(event) => console.log('Popover positioned', event)} />
* ```
*/
onPosition?: (event: PopoverPositionEvent) => void;
/**
* Fires when the Popover is focused and a key is pressed.
* Provides the event details.
*
* @example
* ```jsx
* <Popover onKeyDown={(event) => console.log('Key pressed', event)} />
* ```
*/
onKeyDown?: (event: PopoverKeyDownEvent) => void;
/**
* Specifies the children elements of the Popover.
* Used to define the content of the Popover.
*
* @example
* ```jsx
* <Popover>
* <div>Popover Content</div>
* </Popover>
* ```
*/
children?: React.ReactNode;
}
export declare class Tooltip extends React_2.PureComponent<TooltipProps, TooltipState> {
/**
* @hidden
*/
static propTypes: {
anchorElement: default_2.Requireable<string>;
content: default_2.Requireable<(...args: any[]) => any>;
filter: default_2.Requireable<(...args: any[]) => any>;
openDelay: default_2.Requireable<number>;
position: default_2.Requireable<string>;
updateInterval: default_2.Requireable<number>;
showOption: default_2.Requireable<object>;
};
static defaultProps: {
anchorElement: string;
openDelay: number;
position: string;
showCallout: boolean;
parentTitle: boolean;
};
/**
* @hidden
*/
static contextType: React_2.Context<ZIndexContextType>;
/**
* @hidden
*/
context: React_2.ContextType<typeof ZIndexContext>;
/**
* @hidden
*/
readonly state: TooltipState;
private top;
private left;
private openTimeoutId?;
private updateIntervalId?;
private willOpen;
/**
* @hidden
*/
componentDidMount(): void;
/**
* @hidden
*/
componentWillUnmount(): void;
/**
* @hidden
*/
componentDidUpdate(): void;
/**
* The method is used on the MouseOut event to hide the Tooltip.
*/
handleMouseOut: (event: any) => void;
private compareTargets;
private handleEscape;
/**
* @hidden
*/
handleTargetItemClick: (event: React_2.MouseEvent<HTMLDivElement, MouseEvent>) => void;
private handleKeyDown;
/**
* Used on the `MouseOver` event to show the Tooltip.
*/
handleMouseOver: (event: any) => void;
/**
* @hidden
*/
render(): "" | JSX.Element | null;
private handleBodyMousemove;
private onClose;
private showToolTip;
private setUpdateInterval;
private onIntervalUpdate;
private isVisible;
private position;
private getTitle;
private calloutClassName;
private getCurrentZIndex;
}
export declare interface TooltipEvent extends BaseEvent<Tooltip> {
}
/**
* @hidden
*/
export declare type TooltipPosition = 'right' | 'left' | 'bottom' | 'top' | 'auto';
export declare interface TooltipPositionEvent extends BaseEvent<Tooltip> {
/**
* The Tooltip element. Useful to get the actual `width` and `height` of rendered Tooltip.
*/
element: HTMLDivElement;
/**
* The current target element. Useful to calculate `top` and `left` position of the Tooltip element.
*/
targetElement: HTMLElement | null;
/**
* The current mouse `top` position;
*/
mouseTop: number;
/**
* The current mouse `left` position.
*/
mouseLeft: number;
/**
* The Tooltip anchor element prop.
*/
anchorElement?: string;
/**
* The Tooltip position prop.
*/
position?: TooltipPosition;
}
/**
* Represents the props of the [KendoReact Tooltip component]({% slug overview_tooltip %}).
*/
export declare interface TooltipProps {
/**
* Specifies the `id` of the wrapping element of the Tooltip component.
* Used to uniquely identify the Tooltip element in the DOM.
*
* @example
* ```jsx
* <Tooltip id="tooltip-id" />
* ```
*/
id?: string;
/**
* Sets the anchor element of the Tooltip.
*
* The available options are:
* - (Default) `pointer`—Positions the Tooltip where the cursor is located.
* - `target`—Positions the Tooltip relative to the target element.
*
* @example
* ```jsx
* <Tooltip anchorElement="target" />
* ```
*/
anchorElement?: string;
/**
* Defines the container to which the Tooltip will be appended.
* Defaults to [`body`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body).
* If set to `null`, the Tooltip will not use React Portal.
*
* @example
* ```jsx
* <Tooltip appendTo={document.getElementById('container')} />
* ```
*/
appendTo?: HTMLElement | null;
/**
* Sets the position of the Tooltip ([see example]({% slug positioning_tooltip %})).
*
* The available options are:
* - (Default) `auto`—Automatically positions the Tooltip based on available space.
* - `right`—Positions the Tooltip to the right of the element.
* - `left`—Positions the Tooltip to the left of the element.
* - `bottom`—Positions the Tooltip below the element.
* - `top`—Positions the Tooltip above the element.
*
* @example
* ```jsx
* <Tooltip position="top" />
* ```
*/
position?: TooltipPosition;
/**
* Specifies additional CSS classes for the Tooltip animation container.
*
* @example
* ```jsx
* <Tooltip className="custom-tooltip-class" />
* ```
*/
className?: string;
/**
* Configures when the Tooltip will be displayed.
* The available options are:
* - `hover`—Displays the Tooltip when the mouse hovers over the target element (default).
* - `click`—Displays the Tooltip when the target element is clicked.
* - `focus`—Displays the Tooltip when the target element is focused.
* - `keys`—Displays the Tooltip when a specific key is pressed while the target element is focused.
* - `none`—Disables the Tooltip display.
*
* @example
* ```jsx
* <Tooltip showOption={{ hover: true, click: false }} />
* ```
*/
showOption?: TooltipShowOptions;
/**
* Sets the content of the Tooltip ([see example]({% slug templates_tooltip %})).
* Can be a string, JSX, or a function returning JSX.
*
* @example
* ```jsx
* <Tooltip content="This is a tooltip" />
* ```
*/
content?: any;
/**
* Specifies the children elements of the Tooltip.
* Used to define the content of the Tooltip.
*
* @example
* ```jsx
* <Tooltip>
* <span>Hover over me</span>
* </Tooltip>
* ```
*/
children?: any;
/**
* Controls the visibility of the Tooltip.
* When set, the Tooltip operates in controlled mode ([see example]({% slug controlledmode_tooltip %})).
* Requires the `targetElement` property to be set.
*
* @example
* ```jsx
* <Tooltip open={true} targetElement={document.getElementById('target')} />
* ```
*/
open?: boolean;
/**
* Specifies a delay in milliseconds before the Tooltip is displayed.
*
* @example
* ```jsx
* <Tooltip openDelay={500} />
* ```
*/
openDelay?: number;
/**
* Enables the Tooltip to display the title of any parent element with a `title` attribute.
*
* @example
* ```jsx
* <Tooltip parentTitle={true} />
* ```
*/
parentTitle?: boolean;
/**
* Determines whether the Tooltip callout (arrow) is displayed.
*
* @example
* ```jsx
* <Tooltip showCallout={false} />
* ```
*/
showCallout?: boolean;
/**
* Specifies the starting point of the Tooltip callout when the position is set to `auto`.
* Accepts a pixel value.
*
* @example
* ```jsx
* <Tooltip setCalloutOnPositionAuto="50%" />
* ```
*/
setCalloutOnPositionAuto?: any;
/**
* Specifies the styles applied to the Tooltip animation container.
*
* @example
* ```jsx
* <Tooltip style={{ backgroundColor: 'blue' }} />
* ```
*/
style?: React.CSSProperties;
/**
* Specifies the target element for the Tooltip.
* Required when the Tooltip is in controlled mode.
*
* @example
* ```jsx
* <Tooltip targetElement={document.getElementById('target')} />
* ```
*/
targetElement?: any;
/**
* Specifies additional CSS classes for the Tooltip DOM element.
*
* @example
* ```jsx
* <Tooltip tooltipClassName="custom-tooltip" />
* ```
*/
tooltipClassName?: string;
/**
* Specifies the styles applied to the Tooltip DOM element.
*
* @example
* ```jsx
* <Tooltip tooltipStyle={{ color: 'red' }} />
* ```
*/
tooltipStyle?: React.CSSProperties;
/**
* Fires when the Tooltip is shown.
* Provides the event details.
*
* @example
* ```jsx
* <Tooltip onOpen={(event) => console.log('Tooltip opened', event)} />
* ```
*/
onOpen?: (event: TooltipEvent) => void;
/**
* Fires when the Tooltip is hidden.
* Provides the event details.
*
* @example
* ```jsx
* <Tooltip onClose={(event) => console.log('Tooltip closed', event)} />
* ```
*/
onClose?: (event: TooltipEvent) => void;
/**
* Callback function triggered when the Tooltip calculates its position.
* Allows customization of the `top` and `left` position values.
*
* @example
* ```jsx
* <Tooltip onPosition={(event) => ({ top: 100, left: 200 })} />
* ```
*/
onPosition?: (event: TooltipPositionEvent) => {
top: number;
left: number;
};
/**
* Callback function to determine if the Tooltip should be displayed for a specific target element ([see example]({% slug filter_elements_tooltip %})).
*
* @example
* ```jsx
* <Tooltip filter={(target) => target.tagName === 'BUTTON'} />
* ```
*/
filter?: (target: HTMLElement) => void;
/**
* Specifies the interval in milliseconds for the Tooltip to check for title changes.
* By default, the Tooltip does not track title updates.
*
* @example
* ```jsx
* <Tooltip updateInterval={1000} />
* ```
*/
updateInterval?: number;
}
/**
* Specifies when the options of the [showTooltip](slug:api_tooltip_tooltipprops#toc-showoption) props.
* - `hover`—Shows the Tooltip when the mouse hovers over the target element(Set to `true` by default).
* - `click`—Shows the Tooltip when the target element is clicked(Set to `false` by default).
* - `focus`—Shows the Tooltip when the target element is focused(Set to `false` by default).
* - `keys`—Shows the Tooltip when the target element is focused and a specific key is pressed(Set to `false` by default).
* - `none`—Doesn't show the Tooltip(Set to `false` by default).
*/
declare type TooltipShowOptions = {
hover?: boolean;
click?: boolean;
focus?: boolean;
keys?: string[];
none?: boolean;
};
/**
* @hidden
*/
declare interface TooltipState {
targetElement: HTMLElement | null;
open: boolean;
title: string;
}
export { }