@syncfusion/react-navigations
Version:
A package of Pure React navigation components such as Toolbar and Context-menu which is used to navigate from one page to another
262 lines (261 loc) • 8.44 kB
TypeScript
import { HTMLAttributes } from 'react';
import * as React from 'react';
/**
* Interface for select event arguments when an item is selected from the ContextMenu.
*/
export interface MenuEvent {
/**
* Specifies the item data object of the selected menu item.
*
* @default -
*/
item: MenuItemProps;
/**
* Specifies the React synthetic event triggered by the user interaction.
*
* @default -
*/
event?: React.SyntheticEvent;
}
/**
* Interface for menu item model.
*/
export interface MenuItemProps {
/**
* Specifies the display text for the menu item.
*
* @default -
*/
text?: string;
/**
* Specifies the unique identifier for the menu item.
*
* @default -
*/
id?: string;
/**
* Specifies the icon CSS class or React node for the menu item that is used to include an icon.
* Can be a string (CSS class) or a React element.
*
* @default -
*/
icon?: string | React.ReactNode;
/**
* Specifies the URL for the menu item that creates an anchor link to navigate to the provided URL.
* When clicked, the browser will navigate to this URL.
*
* @default -
*/
url?: string;
/**
* Specifies a separator between the items. Separators are used to group menu items visually.
* When true, renders a horizontal line instead of a clickable menu item.
*
* @default false
*/
separator?: boolean;
/**
* Specifies the sub menu items as an array of MenuItem models for creating nested menu structures.
*
* @default []
*/
items?: MenuItemProps[];
/**
* Specifies the htmlAttributes property to support adding custom HTML attributes to the menu item.
* These attributes will be directly applied to the rendered list item element.
*
* @default -
*/
htmlAttributes?: HTMLAttributes<HTMLLIElement>;
/**
* Specifies whether the item is disabled or not. When true, the item will be non-interactive
* and displayed with a disabled visual state.
*
* @default false
*/
disabled?: boolean;
}
/**
* Specifies the animation effect for the ContextMenu.
*
*/
export type MenuEffect = 'None' | 'SlideDown' | 'ZoomIn' | 'FadeIn';
/**
* Interface for ContextMenu animation settings that controls how the menu appears.
*/
export interface MenuAnimationProp {
/**
* Specifies the effect shown in the ContextMenu transform.
* The possible effects are:
* * None: Specifies the ContextMenu transform with no animation effect.
* * SlideDown: Specifies the ContextMenu transform with slide down effect.
* * ZoomIn: Specifies the ContextMenu transform with zoom in effect.
* * FadeIn: Specifies the ContextMenu transform with fade in effect.
*
* @default 'FadeIn'
*/
effect?: MenuEffect;
/**
* Specifies the time duration in milliseconds for the transform animation.
*
* @default 400
*/
duration?: number;
/**
* Specifies the easing effect applied during the transform animation.
*
* @default 'ease'
*/
easing?: string;
}
/**
* Interface for ContextMenu component props.
*/
export interface ContextMenuProps {
/**
* Specifies whether to show the sub menu on click instead of hover.
* When set to true, the sub menu will open only on mouse click rather than on hover.
*
* @default false
*/
itemOnClick?: boolean;
/**
* Specifies menu items with their properties which will be rendered as ContextMenu.
* This array defines the structure and content of the menu.
*
* @default []
*/
items?: MenuItemProps[];
/**
* Specifies the delay time in milliseconds before opening the submenu when hovering.
*
* @default 0
*/
hoverDelay?: number;
/**
* Specifies the animation settings for the ContextMenu open.
*
* @default { duration: 400, easing: 'ease', effect: 'FadeIn' }
*/
animation?: MenuAnimationProp;
/**
* Specifies the visibility of the ContextMenu.
* If set to true, the ContextMenu is displayed. If false, it is hidden.
*
* @default -
*/
open?: boolean;
/**
* Specifies the position (left/top coordinates) of the ContextMenu.
* This determines where the menu will appear on the screen.
*
* @default -
*/
offset?: {
left: number;
top: number;
};
/**
* Specifies target element on which the ContextMenu should be opened. When provided, ContextMenu
* events on this element will automatically trigger the context menu to appear at the cursor position.
*
* The standard contextmenu event is not supported on iOS devices, so this component automatically
* implements a tapHold touch event handler when iOS is detected. This ensures consistent context menu
* functionality across all platforms and devices. If you prefer to use your own event handling mechanism
* or need different trigger behaviors, you can omit this prop and manually control menu display with
* the `open` and `offset` props instead.
*
* @default -
*/
targetRef?: React.RefObject<HTMLElement>;
/**
* Specifies whether to close the ContextMenu when the document is scrolled.
* When set to true, scrolling the page will automatically close the menu.
*
* @default true
*/
closeOnScroll?: boolean;
/**
* Specifies a custom template for menu items. This function receives the entire item object
* as an argument and should return a React node that will replace the default content.
*
* @default -
*/
itemTemplate?: (item: MenuItemProps) => React.ReactNode;
/**
* Specifies the callback function that triggers before open the ContextMenu.
*
* @event onOpen
*/
onOpen?: (event: Event) => void;
/**
* Specifies the callback function that triggers before closing the ContextMenu.
*
* @event onClose
*/
onClose?: (event: Event) => void;
/**
* Specifies the callback function that triggers when selecting a ContextMenu item.
*
* * item - Specifies the item data object of the selected menu item.
* * event - Specifies the React synthetic event triggered by the user interaction.
*
* @event onSelect
*/
onSelect?: (args: MenuEvent) => void;
}
/**
* Interface for ContextMenu component instance.
*/
export interface IContextMenu extends ContextMenuProps {
/**
* Specifies the DOM element of the ContextMenu.
*
* @private
*/
element: HTMLDivElement | null;
}
type ContextMenuComponentProps = ContextMenuProps & Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'>;
type MenuItemComponentProps = MenuItemProps & Omit<MenuItemProps, 'items' | 'htmlAttributes'> & HTMLAttributes<HTMLLIElement>;
/**
* The MenuItem component represents an individual item within a ContextMenu.
* It serves as a configuration component and doesn't render anything directly.
*
* @example
* ```jsx
* <ContextMenu>
* <MenuItem text="File">
* <MenuItem text="New" />
* <MenuItem text="Open" />
* <MenuItem text="Save" />
* </MenuItem>
* <MenuItem separator={true} />
* <MenuItem text="Edit" icon={<svg>...</svg>}>
* <MenuItem text="Cut" icon={<svg>...</svg>} />
* </MenuItem>
* </ContextMenu>
* ```
*
* @returns {null} This is a wrapper component that doesn't render anything directly.
*/
export declare const MenuItem: React.FC<MenuItemComponentProps>;
/**
* The ContextMenu component displays a menu with a list of options when triggered by a right-click.
* It supports nested submenus, keyboard navigation, icons, and various animation effects.
*
* ```typescript
* const targetRef = useRef<HTMLButtonElement>(null);
* return (
* <div >
* <button ref={targetRef}> Right Click Me </button>
* <ContextMenu targetRef={targetRef as React.RefObject<HTMLElement>}>
* <MenuItem text="Cut" />
* <MenuItem text="Copy" />
* <MenuItem text="Rename" />
* </ContextMenu>
* </div>
* );
* ```
*/
export declare const ContextMenu: React.ForwardRefExoticComponent<ContextMenuComponentProps & React.RefAttributes<IContextMenu>>;
export default ContextMenu;