@coreui/react
Version:
UI Components Library for React.js
139 lines (138 loc) • 5.17 kB
TypeScript
import { ElementType, HTMLAttributes } from 'react';
import type { Options } from '@popperjs/core';
import { PolymorphicRefForwardingComponent } from '../../helpers';
import type { Placements } from '../../types';
import type { Alignments } from './types';
export interface CDropdownProps extends HTMLAttributes<HTMLDivElement | HTMLLIElement> {
/**
* Specifies the alignment of the React Dropdown Menu within this React Dropdown.
*
* @example
* // Align dropdown menu to the end on large devices, otherwise start
* <CDropdown alignment={{ lg: 'end', xs: 'start' }}>
* <CDropdownToggle>Toggle dropdown</CDropdownToggle>
* <CDropdownMenu>
* <CDropdownItem>Action</CDropdownItem>
* <CDropdownItem>Another Action</CDropdownItem>
* </CDropdownMenu>
* </CDropdown>
*
* @type 'start' | 'end' | { xs: 'start' | 'end' } | { sm: 'start' | 'end' } | { md: 'start' | 'end' } | { lg: 'start' | 'end' } | { xl: 'start' | 'end'} | { xxl: 'start' | 'end'}
*/
alignment?: Alignments;
/**
* Determines the root node component (native HTML element or a custom React component) for the React Dropdown.
*/
as?: ElementType;
/**
* Configures automatic closing behavior for the React Dropdown:
* - `true` - Close on clicks inside or outside of the React Dropdown Menu.
* - `false` - Disable auto-close; manually call `hide` or `toggle` (also not closed by `Escape`).
* - `'inside'` - Close only when clicking inside the React Dropdown Menu.
* - `'outside'` - Close only when clicking outside the React Dropdown Menu.
*
* @example
* // Close only when user clicks outside of the menu
* <CDropdown autoClose="outside" />
*/
autoClose?: 'inside' | 'outside' | boolean;
/**
* Adds custom classes to the React Dropdown root element.
*/
className?: string;
/**
* Appends the React Dropdown Menu to a specific element. You can pass an HTML element or a function returning an element. Defaults to `document.body`.
*
* @example
* // Append the menu to a custom container
* const myContainer = document.getElementById('my-container')
*
* <CDropdown container={myContainer} />
*
* @since 4.11.0
*/
container?: DocumentFragment | Element | (() => DocumentFragment | Element | null) | null;
/**
* Applies a darker color scheme to the React Dropdown Menu, often used within dark navbars.
*/
dark?: boolean;
/**
* Specifies the direction of the React Dropdown.
*/
direction?: 'center' | 'dropup' | 'dropup-center' | 'dropend' | 'dropstart';
/**
* Defines x and y offsets ([x, y]) for the React Dropdown Menu relative to its target.
*
* @example
* // Offset the menu 10px in X and 5px in Y direction
* <CDropdown offset={[10, 5]}>
* ...
* </CDropdown>
*/
offset?: [number, number];
/**
* Callback fired right before the React Dropdown becomes hidden.
*
* @since 4.9.0
*/
onHide?: () => void;
/**
* Callback fired immediately after the React Dropdown is displayed.
*/
onShow?: () => void;
/**
* Determines the placement of the React Dropdown Menu after Popper.js modifiers.
*
* @type 'auto' | 'auto-start' | 'auto-end' | 'top-end' | 'top' | 'top-start' | 'bottom-end' | 'bottom' | 'bottom-start' | 'right-start' | 'right' | 'right-end' | 'left-start' | 'left' | 'left-end'
*/
placement?: Placements;
/**
* Enables or disables dynamic positioning via Popper.js for the React Dropdown Menu.
*/
popper?: boolean;
/**
* Provides a custom Popper.js configuration or a function that returns a modified Popper.js configuration for advanced positioning of the React Dropdown Menu. [Read more](https://popper.js.org/docs/v2/constructors/#options)
*
* @example
* // Providing a custom popper config
* <CDropdown
* popperConfig={{
* modifiers: [
* {
* name: 'flip',
* options: { fallbackPlacements: ['bottom', 'top'] },
* },
* ],
* }}
* >...</CDropdown>
*
* @since 5.5.0
*/
popperConfig?: Partial<Options> | ((defaultPopperConfig: Partial<Options>) => Partial<Options>);
/**
* Renders the React Dropdown Menu using a React Portal, allowing it to escape the DOM hierarchy for improved positioning.
*
* @since 4.8.0
*/
portal?: boolean;
/**
* Defines the visual variant of the React Dropdown
*/
variant?: 'btn-group' | 'dropdown' | 'input-group' | 'nav-item';
/**
* Controls the visibility of the React Dropdown Menu:
* - `true` - Visible
* - `false` - Hidden
*
* @example
* // Programmatically manage the dropdown visibility
* const [visible, setVisible] = useState(false)
*
* <CDropdown visible={visible}>
* ...
* </CDropdown>
*
*/
visible?: boolean;
}
export declare const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>;