Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 7c91c99

Browse files
mrholekmrholek
committedJan 28, 2025
feat(CDropdown, CPopover, CTooltip): allow passing custom popper configuration
1 parent cb1ef1f commit 7c91c99

File tree

7 files changed

+506
-158
lines changed

7 files changed

+506
-158
lines changed
 

‎packages/coreui-react/src/components/dropdown/CDropdown.tsx

Lines changed: 106 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ import React, {
1010
} from 'react'
1111
import PropTypes from 'prop-types'
1212
import classNames from 'classnames'
13+
import type { Options } from '@popperjs/core'
1314

1415
import { PolymorphicRefForwardingComponent } from '../../helpers'
1516
import { useForkedRef, usePopper } from '../../hooks'
@@ -22,77 +23,148 @@ import { getPlacement } from './utils'
2223

2324
export interface CDropdownProps extends HTMLAttributes<HTMLDivElement | HTMLLIElement> {
2425
/**
25-
* Set aligment of dropdown menu.
26+
* Specifies the alignment of the React Dropdown Menu within this React Dropdown.
27+
*
28+
* @example
29+
* // Align dropdown menu to the end on large devices, otherwise start
30+
* <CDropdown alignment={{ lg: 'end', xs: 'start' }}>
31+
* <CDropdownToggle>Toggle dropdown</CDropdownToggle>
32+
* <CDropdownMenu>
33+
* <CDropdownItem>Action</CDropdownItem>
34+
* <CDropdownItem>Another Action</CDropdownItem>
35+
* </CDropdownMenu>
36+
* </CDropdown>
2637
*
2738
* @type 'start' | 'end' | { xs: 'start' | 'end' } | { sm: 'start' | 'end' } | { md: 'start' | 'end' } | { lg: 'start' | 'end' } | { xl: 'start' | 'end'} | { xxl: 'start' | 'end'}
2839
*/
2940
alignment?: Alignments
41+
3042
/**
31-
* Component used for the root node. Either a string to use a HTML element or a component.
43+
* Determines the root node component (native HTML element or a custom React component) for the React Dropdown.
3244
*/
3345
as?: ElementType
46+
3447
/**
35-
* Configure the auto close behavior of the dropdown:
36-
* - `true` - the dropdown will be closed by clicking outside or inside the dropdown menu.
37-
* - `false` - the dropdown will be closed by clicking the toggle button and manually calling hide or toggle method. (Also will not be closed by pressing esc key)
38-
* - `'inside'` - the dropdown will be closed (only) by clicking inside the dropdown menu.
39-
* - `'outside'` - the dropdown will be closed (only) by clicking outside the dropdown menu.
48+
* Configures automatic closing behavior for the React Dropdown:
49+
* - `true` - Close on clicks inside or outside of the React Dropdown Menu.
50+
* - `false` - Disable auto-close; manually call `hide` or `toggle` (also not closed by `Escape`).
51+
* - `'inside'` - Close only when clicking inside the React Dropdown Menu.
52+
* - `'outside'` - Close only when clicking outside the React Dropdown Menu.
53+
*
54+
* @example
55+
* // Close only when user clicks outside of the menu
56+
* <CDropdown autoClose="outside" />
4057
*/
4158
autoClose?: 'inside' | 'outside' | boolean
59+
4260
/**
43-
* A string of all className you want applied to the base component.
61+
* Adds custom classes to the React Dropdown root element.
4462
*/
4563
className?: string
64+
4665
/**
47-
* Appends the react dropdown menu to a specific element. You can pass an HTML element or function that returns a single element. By default `document.body`.
66+
* 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`.
67+
*
68+
* @example
69+
* // Append the menu to a custom container
70+
* const myContainer = document.getElementById('my-container')
71+
*
72+
* <CDropdown container={myContainer} />
4873
*
4974
* @since 4.11.0
5075
*/
5176
container?: DocumentFragment | Element | (() => DocumentFragment | Element | null) | null
77+
5278
/**
53-
* Sets a darker color scheme to match a dark navbar.
79+
* Applies a darker color scheme to the React Dropdown Menu, often used within dark navbars.
5480
*/
5581
dark?: boolean
82+
5683
/**
57-
* Sets a specified direction and location of the dropdown menu.
84+
* Specifies the direction of the React Dropdown.
5885
*/
5986
direction?: 'center' | 'dropup' | 'dropup-center' | 'dropend' | 'dropstart'
87+
6088
/**
61-
* Offset of the dropdown menu relative to its target.
89+
* Defines x and y offsets ([x, y]) for the React Dropdown Menu relative to its target.
90+
*
91+
* @example
92+
* // Offset the menu 10px in X and 5px in Y direction
93+
* <CDropdown offset={[10, 5]}>
94+
* ...
95+
* </CDropdown>
6296
*/
6397
offset?: [number, number]
98+
6499
/**
65-
* Callback fired when the component requests to be hidden.
100+
* Callback fired right before the React Dropdown becomes hidden.
66101
*
67102
* @since 4.9.0
68103
*/
69104
onHide?: () => void
105+
70106
/**
71-
* Callback fired when the component requests to be shown.
107+
* Callback fired immediately after the React Dropdown is displayed.
72108
*/
73109
onShow?: () => void
110+
74111
/**
75-
* Describes the placement of your component after Popper.js has applied all the modifiers that may have flipped or altered the originally provided placement property.
112+
* Determines the placement of the React Dropdown Menu after Popper.js modifiers.
76113
*
77-
* @type 'auto' | 'top-end' | 'top' | 'top-start' | 'bottom-end' | 'bottom' | 'bottom-start' | 'right-start' | 'right' | 'right-end' | 'left-start' | 'left' | 'left-end'
114+
* @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'
78115
*/
79116
placement?: Placements
117+
80118
/**
81-
* If you want to disable dynamic positioning set this property to `true`.
119+
* Enables or disables dynamic positioning via Popper.js for the React Dropdown Menu.
82120
*/
83121
popper?: boolean
122+
123+
/**
124+
* 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)
125+
*
126+
* @example
127+
* // Providing a custom popper config
128+
* <CDropdown
129+
* popperConfig={{
130+
* modifiers: [
131+
* {
132+
* name: 'flip',
133+
* options: { fallbackPlacements: ['bottom', 'top'] },
134+
* },
135+
* ],
136+
* }}
137+
* >...</CDropdown>
138+
*
139+
* @since 5.5.0
140+
*/
141+
popperConfig?: Partial<Options> | ((defaultPopperConfig: Partial<Options>) => Partial<Options>)
142+
84143
/**
85-
* Generates dropdown menu using createPortal.
144+
* Renders the React Dropdown Menu using a React Portal, allowing it to escape the DOM hierarchy for improved positioning.
86145
*
87146
* @since 4.8.0
88147
*/
89148
portal?: boolean
149+
90150
/**
91-
* Set the dropdown variant to an btn-group, dropdown, input-group, and nav-item.
151+
* Defines the visual variant of the React Dropdown
92152
*/
93153
variant?: 'btn-group' | 'dropdown' | 'input-group' | 'nav-item'
154+
94155
/**
95-
* Toggle the visibility of dropdown menu component.
156+
* Controls the visibility of the React Dropdown Menu:
157+
* - `true` - Visible
158+
* - `false` - Hidden
159+
*
160+
* @example
161+
* // Programmatically manage the dropdown visibility
162+
* const [visible, setVisible] = useState(false)
163+
*
164+
* <CDropdown visible={visible}>
165+
* ...
166+
* </CDropdown>
167+
*
96168
*/
97169
visible?: boolean
98170
}
@@ -126,12 +198,13 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
126198
onShow,
127199
placement = 'bottom-start',
128200
popper = true,
201+
popperConfig,
129202
portal = false,
130203
variant = 'btn-group',
131204
visible = false,
132205
...rest
133206
},
134-
ref,
207+
ref
135208
) => {
136209
const dropdownRef = useRef<HTMLDivElement>(null)
137210
// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -161,7 +234,7 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
161234
setVisible,
162235
}
163236

164-
const popperConfig = {
237+
const defaultPopperConfig = {
165238
modifiers: [
166239
{
167240
name: 'offset',
@@ -173,14 +246,20 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
173246
placement: getPlacement(placement, direction, alignment, isRTL(dropdownMenuRef.current)),
174247
}
175248

249+
const computedPopperConfig: Partial<Options> = {
250+
...defaultPopperConfig,
251+
...(typeof popperConfig === 'function' ? popperConfig(defaultPopperConfig) : popperConfig),
252+
}
253+
176254
useEffect(() => {
177255
setVisible(visible)
178256
}, [visible])
179257

180258
useEffect(() => {
181259
if (_visible && dropdownToggleRef.current && dropdownMenuRef.current) {
182260
dropdownToggleRef.current.focus()
183-
popper && initPopper(dropdownToggleRef.current, dropdownMenuRef.current, popperConfig)
261+
popper &&
262+
initPopper(dropdownToggleRef.current, dropdownMenuRef.current, computedPopperConfig)
184263
window.addEventListener('mouseup', handleMouseUp)
185264
window.addEventListener('keyup', handleKeyup)
186265
dropdownToggleRef.current.addEventListener('keydown', handleKeydown)
@@ -209,7 +288,7 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
209288
event.preventDefault()
210289
const target = event.target as HTMLElement
211290
const items: HTMLElement[] = Array.from(
212-
dropdownMenuRef.current.querySelectorAll('.dropdown-item:not(.disabled):not(:disabled)'),
291+
dropdownMenuRef.current.querySelectorAll('.dropdown-item:not(.disabled):not(:disabled)')
213292
)
214293
getNextActiveElement(items, target, event.key === 'ArrowDown', true).focus()
215294
}
@@ -258,7 +337,7 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
258337
[`${direction}`]:
259338
direction && direction !== 'center' && direction !== 'dropup-center',
260339
},
261-
className,
340+
className
262341
)}
263342
{...rest}
264343
ref={forkedRef}
@@ -268,7 +347,7 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
268347
)}
269348
</CDropdownContext.Provider>
270349
)
271-
},
350+
}
272351
)
273352

274353
const alignmentDirection = PropTypes.oneOf<Directions>(['start', 'end'])
@@ -297,6 +376,7 @@ CDropdown.propTypes = {
297376
onShow: PropTypes.func,
298377
placement: placementPropType,
299378
popper: PropTypes.bool,
379+
popperConfig: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
300380
portal: PropTypes.bool,
301381
variant: PropTypes.oneOf(['btn-group', 'dropdown', 'input-group', 'nav-item']),
302382
visible: PropTypes.bool,

‎packages/coreui-react/src/components/popover/CPopover.tsx

Lines changed: 103 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import React, {
99
} from 'react'
1010
import classNames from 'classnames'
1111
import PropTypes from 'prop-types'
12+
import type { Options } from '@popperjs/core'
1213

1314
import { CConditionalPortal } from '../conditional-portal'
1415
import { useForkedRef, usePopper } from '../../hooks'
@@ -18,65 +19,132 @@ import { executeAfterTransition, getRTLPlacement } from '../../utils'
1819

1920
export interface CPopoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'content'> {
2021
/**
21-
* Apply a CSS fade transition to the popover.
22+
* Adds a fade transition animation to the React Popover.
2223
*
2324
* @since 4.9.0
2425
*/
2526
animation?: boolean
27+
2628
/**
27-
* A string of all className you want applied to the component.
29+
* Custom class name(s) for additional styling.
2830
*/
2931
className?: string
32+
3033
/**
31-
* Appends the react popover to a specific element. You can pass an HTML element or function that returns a single element. By default `document.body`.
34+
* Defines the container element to which the React Popover is appended.
35+
* Accepts:
36+
* - A DOM element (`HTMLElement` or `DocumentFragment`)
37+
* - A function that returns a single element
38+
* - `null` (defaults to `document.body`)
39+
*
40+
* @example
41+
* <CPopover container={document.getElementById('my-container')}>...</CPopover>
3242
*
43+
* @default document.body
3344
* @since 4.11.0
3445
*/
3546
container?: DocumentFragment | Element | (() => DocumentFragment | Element | null) | null
47+
3648
/**
37-
* Content node for your component.
49+
* Main content of the React Popover. It can be a string or any valid React node.
3850
*/
3951
content: ReactNode | string
52+
4053
/**
41-
* Offset of the popover relative to its target.
42-
*/
43-
offset?: [number, number]
44-
/**
45-
* The delay for displaying and hiding the popover (in milliseconds). When a numerical value is provided, the delay applies to both the hide and show actions. The object structure for specifying the delay is as follows: delay: `{ 'show': 500, 'hide': 100 }`.
54+
* Delay (in milliseconds) before showing or hiding the React Popover.
55+
* - If a number is provided, that delay applies to both "show" and "hide".
56+
* - If an object is provided, use separate values for "show" and "hide".
57+
*
58+
* @example
59+
* // Delays 300ms on both show and hide
60+
* <CPopover delay={300}>...</CPopover>
61+
*
62+
* // Delays 500ms on show and 100ms on hide
63+
* <CPopover delay={{ show: 500, hide: 100 }}>...</CPopover>
4664
*
4765
* @since 4.9.0
4866
*/
4967
delay?: number | { show: number; hide: number }
68+
5069
/**
51-
* Specify the desired order of fallback placements by providing a list of placements as an array. The placements should be prioritized based on preference.
70+
* Specifies the fallback placements when the preferred `placement` cannot be met.
5271
*
72+
* @type 'top', 'right', 'bottom', 'left' | ('top', 'right', 'bottom', 'left')[]
5373
* @since 4.9.0
5474
*/
5575
fallbackPlacements?: Placements | Placements[]
76+
5677
/**
57-
* Callback fired when the component requests to be hidden.
78+
* Offset of the React Popover relative to its toggle element, in the form `[x, y]`.
79+
*
80+
* @example
81+
* // Offset the menu 0px in X and 10px in Y direction
82+
* <CPopover offset={[0, 10]}>...</CPopover>
83+
*
84+
* // Offset the menu 5px in both X and Y direction
85+
* <CPopover offset={[5, 5]}>...</CPopover>
86+
*/
87+
offset?: [number, number]
88+
89+
/**
90+
* Invoked when the React Popover is about to hide.
5891
*/
5992
onHide?: () => void
93+
6094
/**
61-
* Callback fired when the component requests to be shown.
95+
* Invoked when the React Popover is about to show.
6296
*/
6397
onShow?: () => void
98+
6499
/**
65-
* Title node for your component.
100+
* Placement of the React Popover. Popper.js may override this based on available space.
66101
*/
67-
title?: ReactNode | string
102+
placement?: 'auto' | 'top' | 'right' | 'bottom' | 'left'
103+
68104
/**
69-
* Sets which event handlers you’d like provided to your toggle prop. You can specify one trigger or an array of them.
105+
* Allows customization of the Popper.js configuration for the React Popover.
106+
* Can be an object or a function returning a modified configuration.
107+
* [Learn more](https://popper.js.org/docs/v2/constructors/#options)
108+
*
109+
* @example
110+
* <CPopover
111+
* popperConfig={(defaultConfig) => ({
112+
* ...defaultConfig,
113+
* strategy: 'fixed',
114+
* modifiers: [
115+
* ...defaultConfig.modifiers,
116+
* { name: 'computeStyles', options: { adaptive: false } },
117+
* ],
118+
* })}
119+
* >...</CPopover>
70120
*
71-
* @type 'hover' | 'focus' | 'click'
121+
* @since 5.5.0
72122
*/
73-
trigger?: Triggers | Triggers[]
123+
popperConfig?: Partial<Options> | ((defaultPopperConfig: Partial<Options>) => Partial<Options>)
124+
74125
/**
75-
* Describes the placement of your component after Popper.js has applied all the modifiers that may have flipped or altered the originally provided placement property.
126+
* Title for the React Popover header. Can be a string or any valid React node.
76127
*/
77-
placement?: 'auto' | 'top' | 'right' | 'bottom' | 'left'
128+
title?: ReactNode | string
129+
78130
/**
79-
* Toggle the visibility of popover component.
131+
* Determines which events trigger the visibility of the React Popover. Can be a single trigger or an array of triggers.
132+
*
133+
* @example
134+
* // Hover-only popover
135+
* <CPopover trigger="hover">...</CPopover>
136+
*
137+
* // Hover + click combined
138+
* <CPopover trigger={['hover', 'click']}>...</CPopover>
139+
*
140+
* @type 'hover' | 'focus' | 'click' | ('hover' | 'focus' | 'click')[]
141+
*/
142+
trigger?: Triggers | Triggers[]
143+
144+
/**
145+
* Controls the visibility of the React Popover.
146+
* - `true` shows the popover.
147+
* - `false` hides the popover.
80148
*/
81149
visible?: boolean
82150
}
@@ -95,12 +163,13 @@ export const CPopover = forwardRef<HTMLDivElement, CPopoverProps>(
95163
onHide,
96164
onShow,
97165
placement = 'top',
166+
popperConfig,
98167
title,
99168
trigger = 'click',
100169
visible,
101170
...rest
102171
},
103-
ref,
172+
ref
104173
) => {
105174
const popoverRef = useRef<HTMLDivElement>(null)
106175
const togglerRef = useRef(null)
@@ -114,30 +183,20 @@ export const CPopover = forwardRef<HTMLDivElement, CPopoverProps>(
114183

115184
const _delay = typeof delay === 'number' ? { show: delay, hide: delay } : delay
116185

117-
const popperConfig = {
186+
const defaultPopperConfig: Partial<Options> = {
118187
modifiers: [
119-
{
120-
name: 'arrow',
121-
options: {
122-
element: '.popover-arrow',
123-
},
124-
},
125-
{
126-
name: 'flip',
127-
options: {
128-
fallbackPlacements: fallbackPlacements,
129-
},
130-
},
131-
{
132-
name: 'offset',
133-
options: {
134-
offset: offset,
135-
},
136-
},
188+
{ name: 'arrow', options: { element: '.popover-arrow' } },
189+
{ name: 'flip', options: { fallbackPlacements } },
190+
{ name: 'offset', options: { offset } },
137191
],
138192
placement: getRTLPlacement(placement, togglerRef.current),
139193
}
140194

195+
const computedPopperConfig: Partial<Options> = {
196+
...defaultPopperConfig,
197+
...(typeof popperConfig === 'function' ? popperConfig(defaultPopperConfig) : popperConfig),
198+
}
199+
141200
useEffect(() => {
142201
if (visible) {
143202
handleShow()
@@ -149,7 +208,7 @@ export const CPopover = forwardRef<HTMLDivElement, CPopoverProps>(
149208

150209
useEffect(() => {
151210
if (mounted && togglerRef.current && popoverRef.current) {
152-
initPopper(togglerRef.current, popoverRef.current, popperConfig)
211+
initPopper(togglerRef.current, popoverRef.current, computedPopperConfig)
153212
setTimeout(() => {
154213
setVisible(true)
155214
}, _delay.show)
@@ -215,7 +274,7 @@ export const CPopover = forwardRef<HTMLDivElement, CPopoverProps>(
215274
fade: animation,
216275
show: _visible,
217276
},
218-
className,
277+
className
219278
)}
220279
id={id}
221280
ref={forkedRef}
@@ -230,7 +289,7 @@ export const CPopover = forwardRef<HTMLDivElement, CPopoverProps>(
230289
</CConditionalPortal>
231290
</>
232291
)
233-
},
292+
}
234293
)
235294

236295
CPopover.propTypes = {
@@ -251,6 +310,7 @@ CPopover.propTypes = {
251310
onHide: PropTypes.func,
252311
onShow: PropTypes.func,
253312
placement: PropTypes.oneOf(['auto', 'top', 'right', 'bottom', 'left']),
313+
popperConfig: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
254314
title: PropTypes.oneOfType([PropTypes.string, PropTypes.node]),
255315
trigger: triggerPropType,
256316
visible: PropTypes.bool,

‎packages/coreui-react/src/components/tooltip/CTooltip.tsx

Lines changed: 94 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import React, {
99
} from 'react'
1010
import classNames from 'classnames'
1111
import PropTypes from 'prop-types'
12+
import type { Options } from '@popperjs/core'
1213

1314
import { CConditionalPortal } from '../conditional-portal'
1415
import { useForkedRef, usePopper } from '../../hooks'
@@ -18,61 +19,124 @@ import { executeAfterTransition, getRTLPlacement } from '../../utils'
1819

1920
export interface CTooltipProps extends Omit<HTMLAttributes<HTMLDivElement>, 'content'> {
2021
/**
21-
* Apply a CSS fade transition to the tooltip.
22+
* Enables or disables the CSS fade transition for the React Tooltip.
2223
*
2324
* @since 4.9.0
2425
*/
2526
animation?: boolean
27+
2628
/**
27-
* A string of all className you want applied to the component.
29+
* Adds a custom class name to the React Tooltip container. Useful for overriding default styles or applying additional design choices.
2830
*/
2931
className?: string
32+
3033
/**
31-
* Appends the react tooltip to a specific element. You can pass an HTML element or function that returns a single element. By default `document.body`.
34+
* Appends the React Tooltip to a specific element instead of the default `document.body`. You may pass:
35+
* - A DOM element (`HTMLElement` or `DocumentFragment`)
36+
* - A function that returns a single element
37+
* - `null`
3238
*
39+
* @example
40+
* <CTooltip container={document.getElementById('my-container')}>...</CTooltip>
41+
*
42+
* @default document.body
3343
* @since 4.11.0
3444
*/
3545
container?: DocumentFragment | Element | (() => DocumentFragment | Element | null) | null
46+
3647
/**
37-
* Content node for your component.
48+
* Content to be displayed within the React Tooltip. Can be a string or any valid React node.
3849
*/
3950
content: ReactNode | string
51+
4052
/**
41-
* The delay for displaying and hiding the tooltip (in milliseconds). When a numerical value is provided, the delay applies to both the hide and show actions. The object structure for specifying the delay is as follows: delay: `{ 'show': 500, 'hide': 100 }`.
53+
* The delay (in milliseconds) before showing or hiding the React Tooltip.
54+
* - If provided as a number, the delay is applied to both "show" and "hide".
55+
* - If provided as an object, it should have distinct "show" and "hide" values.
56+
*
57+
* @example
58+
* // Delays 300ms on both show and hide
59+
* <CTooltip delay={300}>...</CTooltip>
60+
*
61+
* // Delays 500ms on show and 100ms on hide
62+
* <CTooltip delay={{ show: 500, hide: 100 }}>...</CTooltip>
4263
*
4364
* @since 4.9.0
4465
*/
4566
delay?: number | { show: number; hide: number }
67+
4668
/**
47-
* Specify the desired order of fallback placements by providing a list of placements as an array. The placements should be prioritized based on preference.
69+
* Array of fallback placements for the React Tooltip to use when the preferred placement cannot be achieved. These placements are tried in order.
4870
*
71+
* @type 'top', 'right', 'bottom', 'left' | ('top', 'right', 'bottom', 'left')[]
4972
* @since 4.9.0
5073
*/
5174
fallbackPlacements?: Placements | Placements[]
75+
5276
/**
53-
* Offset of the tooltip relative to its target.
77+
* Adjusts the offset of the React Tooltip relative to its target. Expects a tuple `[x-axis, y-axis]`.
78+
*
79+
* @example
80+
* // Offset the menu 0px in X and 10px in Y direction
81+
* <CTooltip offset={[0, 10]}>...</CTooltip>
82+
*
83+
* // Offset the menu 5px in both X and Y direction
84+
* <CTooltip offset={[5, 5]}>...</CTooltip>
5485
*/
5586
offset?: [number, number]
87+
5688
/**
57-
* Callback fired when the component requests to be hidden.
89+
* Callback fired immediately after the React Tooltip is hidden.
5890
*/
5991
onHide?: () => void
92+
6093
/**
61-
* Callback fired when the component requests to be shown.
94+
* Callback fired immediately after the React Tooltip is shown.
6295
*/
6396
onShow?: () => void
97+
6498
/**
65-
* Sets which event handlers you’d like provided to your toggle prop. You can specify one trigger or an array of them.
99+
* Initial placement of the React Tooltip. Note that Popper.js modifiers may alter this placement automatically if there's insufficient space in the chosen position.
100+
*/
101+
placement?: 'auto' | 'top' | 'right' | 'bottom' | 'left'
102+
103+
/**
104+
* Customize the Popper.js configuration used to position the React Tooltip. Pass either an object or a function returning a modified config. [Learn more](https://popper.js.org/docs/v2/constructors/#options)
105+
*
106+
* @example
107+
* <CTooltip
108+
* popperConfig={(defaultConfig) => ({
109+
* ...defaultConfig,
110+
* strategy: 'fixed',
111+
* modifiers: [
112+
* ...defaultConfig.modifiers,
113+
* { name: 'computeStyles', options: { adaptive: false } },
114+
* ],
115+
* })}
116+
* >...</CTooltip>
66117
*
67-
* @type 'hover' | 'focus' | 'click'
118+
* @since 5.5.0
68119
*/
69-
trigger?: Triggers | Triggers[]
120+
popperConfig?: Partial<Options> | ((defaultPopperConfig: Partial<Options>) => Partial<Options>)
121+
70122
/**
71-
* Describes the placement of your component after Popper.js has applied all the modifiers that may have flipped or altered the originally provided placement property.
123+
* Determines the events that toggle the visibility of the React Tooltip. Can be a single trigger or an array of triggers.
124+
*
125+
* @example
126+
* // Hover-only tooltip
127+
* <CTooltip trigger="hover">...</CTooltip>
128+
*
129+
* // Hover + click combined
130+
* <CTooltip trigger={['hover', 'click']}>...</CTooltip>
131+
*
132+
* @type 'hover' | 'focus' | 'click' | ('hover' | 'focus' | 'click')[]
72133
*/
73-
placement?: 'auto' | 'top' | 'right' | 'bottom' | 'left'
134+
trigger?: Triggers | Triggers[]
135+
74136
/**
75-
* Toggle the visibility of tooltip component.
137+
* Controls the visibility of the React Tooltip.
138+
* - `true` to show the tooltip.
139+
* - `false` to hide the tooltip.
76140
*/
77141
visible?: boolean
78142
}
@@ -91,11 +155,12 @@ export const CTooltip = forwardRef<HTMLDivElement, CTooltipProps>(
91155
onHide,
92156
onShow,
93157
placement = 'top',
158+
popperConfig,
94159
trigger = ['hover', 'focus'],
95160
visible,
96161
...rest
97162
},
98-
ref,
163+
ref
99164
) => {
100165
const tooltipRef = useRef<HTMLDivElement>(null)
101166
const togglerRef = useRef(null)
@@ -109,30 +174,20 @@ export const CTooltip = forwardRef<HTMLDivElement, CTooltipProps>(
109174

110175
const _delay = typeof delay === 'number' ? { show: delay, hide: delay } : delay
111176

112-
const popperConfig = {
177+
const defaultPopperConfig: Partial<Options> = {
113178
modifiers: [
114-
{
115-
name: 'arrow',
116-
options: {
117-
element: '.tooltip-arrow',
118-
},
119-
},
120-
{
121-
name: 'flip',
122-
options: {
123-
fallbackPlacements: fallbackPlacements,
124-
},
125-
},
126-
{
127-
name: 'offset',
128-
options: {
129-
offset: offset,
130-
},
131-
},
179+
{ name: 'arrow', options: { element: '.tooltip-arrow' } },
180+
{ name: 'flip', options: { fallbackPlacements } },
181+
{ name: 'offset', options: { offset } },
132182
],
133183
placement: getRTLPlacement(placement, togglerRef.current),
134184
}
135185

186+
const computedPopperConfig: Partial<Options> = {
187+
...defaultPopperConfig,
188+
...(typeof popperConfig === 'function' ? popperConfig(defaultPopperConfig) : popperConfig),
189+
}
190+
136191
useEffect(() => {
137192
if (visible) {
138193
handleShow()
@@ -144,7 +199,7 @@ export const CTooltip = forwardRef<HTMLDivElement, CTooltipProps>(
144199

145200
useEffect(() => {
146201
if (mounted && togglerRef.current && tooltipRef.current) {
147-
initPopper(togglerRef.current, tooltipRef.current, popperConfig)
202+
initPopper(togglerRef.current, tooltipRef.current, computedPopperConfig)
148203
setTimeout(() => {
149204
setVisible(true)
150205
}, _delay.show)
@@ -214,7 +269,7 @@ export const CTooltip = forwardRef<HTMLDivElement, CTooltipProps>(
214269
fade: animation,
215270
show: _visible,
216271
},
217-
className,
272+
className
218273
)}
219274
id={id}
220275
ref={forkedRef}
@@ -228,7 +283,7 @@ export const CTooltip = forwardRef<HTMLDivElement, CTooltipProps>(
228283
</CConditionalPortal>
229284
</>
230285
)
231-
},
286+
}
232287
)
233288

234289
CTooltip.propTypes = {
@@ -248,6 +303,7 @@ CTooltip.propTypes = {
248303
onHide: PropTypes.func,
249304
onShow: PropTypes.func,
250305
placement: PropTypes.oneOf(['auto', 'top', 'right', 'bottom', 'left']),
306+
popperConfig: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
251307
trigger: triggerPropType,
252308
visible: PropTypes.bool,
253309
}

‎packages/docs/content/api/CDropdown.api.mdx

Lines changed: 69 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,15 @@ import CDropdown from '@coreui/react/src/components/dropdown/CDropdown'
2222
</tr>
2323
<tr>
2424
<td colSpan="3">
25-
<p>Set aligment of dropdown menu.</p>
25+
<p>Specifies the alignment of the React Dropdown Menu within this React Dropdown.</p>
26+
<JSXDocs code={`// Align dropdown menu to the end on large devices, otherwise start
27+
<CDropdown alignment={{ lg: 'end', xs: 'start' }}>
28+
<CDropdownToggle>Toggle dropdown</CDropdownToggle>
29+
<CDropdownMenu>
30+
<CDropdownItem>Action</CDropdownItem>
31+
<CDropdownItem>Another Action</CDropdownItem>
32+
</CDropdownMenu>
33+
</CDropdown>`} />
2634
</td>
2735
</tr>
2836
<tr id="cdropdown-as">
@@ -32,7 +40,7 @@ import CDropdown from '@coreui/react/src/components/dropdown/CDropdown'
3240
</tr>
3341
<tr>
3442
<td colSpan="3">
35-
<p>Component used for the root node. Either a string to use a HTML element or a component.</p>
43+
<p>Determines the root node component (native HTML element or a custom React component) for the React Dropdown.</p>
3644
</td>
3745
</tr>
3846
<tr id="cdropdown-auto-close">
@@ -42,13 +50,15 @@ import CDropdown from '@coreui/react/src/components/dropdown/CDropdown'
4250
</tr>
4351
<tr>
4452
<td colSpan="3">
45-
<p>Configure the auto close behavior of the dropdown:</p>
53+
<p>Configures automatic closing behavior for the React Dropdown:</p>
4654
<ul>
47-
<li><code>{`true`}</code> - the dropdown will be closed by clicking outside or inside the dropdown menu.</li>
48-
<li><code>{`false`}</code> - the dropdown will be closed by clicking the toggle button and manually calling hide or toggle method. (Also will not be closed by pressing esc key)</li>
49-
<li><code>{`'inside'`}</code> - the dropdown will be closed (only) by clicking inside the dropdown menu.</li>
50-
<li><code>{`'outside'`}</code> - the dropdown will be closed (only) by clicking outside the dropdown menu.</li>
55+
<li><code>{`true`}</code> - Close on clicks inside or outside of the React Dropdown Menu.</li>
56+
<li><code>{`false`}</code> - Disable auto-close; manually call <code>{`hide`}</code> or <code>{`toggle`}</code> (also not closed by <code>{`Escape`}</code>).</li>
57+
<li><code>{`'inside'`}</code> - Close only when clicking inside the React Dropdown Menu.</li>
58+
<li><code>{`'outside'`}</code> - Close only when clicking outside the React Dropdown Menu.</li>
5159
</ul>
60+
<JSXDocs code={`// Close only when user clicks outside of the menu
61+
<CDropdown autoClose="outside" />`} />
5262
</td>
5363
</tr>
5464
<tr id="cdropdown-class-name">
@@ -58,7 +68,7 @@ import CDropdown from '@coreui/react/src/components/dropdown/CDropdown'
5868
</tr>
5969
<tr>
6070
<td colSpan="3">
61-
<p>A string of all className you want applied to the base component.</p>
71+
<p>Adds custom classes to the React Dropdown root element.</p>
6272
</td>
6373
</tr>
6474
<tr id="cdropdown-container">
@@ -68,7 +78,11 @@ import CDropdown from '@coreui/react/src/components/dropdown/CDropdown'
6878
</tr>
6979
<tr>
7080
<td colSpan="3">
71-
<p>Appends the react dropdown menu to a specific element. You can pass an HTML element or function that returns a single element. By default <code>{`document.body`}</code>.</p>
81+
<p>Appends the React Dropdown Menu to a specific element. You can pass an HTML element or a function returning an element. Defaults to <code>{`document.body`}</code>.</p>
82+
<JSXDocs code={`// Append the menu to a custom container
83+
const myContainer = document.getElementById('my-container')
84+
85+
<CDropdown container={myContainer} />`} />
7286
</td>
7387
</tr>
7488
<tr id="cdropdown-dark">
@@ -78,7 +92,7 @@ import CDropdown from '@coreui/react/src/components/dropdown/CDropdown'
7892
</tr>
7993
<tr>
8094
<td colSpan="3">
81-
<p>Sets a darker color scheme to match a dark navbar.</p>
95+
<p>Applies a darker color scheme to the React Dropdown Menu, often used within dark navbars.</p>
8296
</td>
8397
</tr>
8498
<tr id="cdropdown-direction">
@@ -88,7 +102,7 @@ import CDropdown from '@coreui/react/src/components/dropdown/CDropdown'
88102
</tr>
89103
<tr>
90104
<td colSpan="3">
91-
<p>Sets a specified direction and location of the dropdown menu.</p>
105+
<p>Specifies the direction of the React Dropdown.</p>
92106
</td>
93107
</tr>
94108
<tr id="cdropdown-offset">
@@ -98,7 +112,11 @@ import CDropdown from '@coreui/react/src/components/dropdown/CDropdown'
98112
</tr>
99113
<tr>
100114
<td colSpan="3">
101-
<p>Offset of the dropdown menu relative to its target.</p>
115+
<p>Defines x and y offsets ([x, y]) for the React Dropdown Menu relative to its target.</p>
116+
<JSXDocs code={`// Offset the menu 10px in X and 5px in Y direction
117+
<CDropdown offset={[10, 5]}>
118+
...
119+
</CDropdown>`} />
102120
</td>
103121
</tr>
104122
<tr id="cdropdown-on-hide">
@@ -108,7 +126,7 @@ import CDropdown from '@coreui/react/src/components/dropdown/CDropdown'
108126
</tr>
109127
<tr>
110128
<td colSpan="3">
111-
<p>Callback fired when the component requests to be hidden.</p>
129+
<p>Callback fired right before the React Dropdown becomes hidden.</p>
112130
</td>
113131
</tr>
114132
<tr id="cdropdown-on-show">
@@ -118,17 +136,17 @@ import CDropdown from '@coreui/react/src/components/dropdown/CDropdown'
118136
</tr>
119137
<tr>
120138
<td colSpan="3">
121-
<p>Callback fired when the component requests to be shown.</p>
139+
<p>Callback fired immediately after the React Dropdown is displayed.</p>
122140
</td>
123141
</tr>
124142
<tr id="cdropdown-placement">
125143
<td className="text-primary fw-semibold">placement<a href="#cdropdown-placement" aria-label="CDropdown placement permalink" className="anchor-link after">#</a></td>
126144
<td><code>{`bottom-start`}</code></td>
127-
<td><code>{`'auto'`}</code>, <code>{`'top-end'`}</code>, <code>{`'top'`}</code>, <code>{`'top-start'`}</code>, <code>{`'bottom-end'`}</code>, <code>{`'bottom'`}</code>, <code>{`'bottom-start'`}</code>, <code>{`'right-start'`}</code>, <code>{`'right'`}</code>, <code>{`'right-end'`}</code>, <code>{`'left-start'`}</code>, <code>{`'left'`}</code>, <code>{`'left-end'`}</code></td>
145+
<td><code>{`'auto'`}</code>, <code>{`'auto-start'`}</code>, <code>{`'auto-end'`}</code>, <code>{`'top-end'`}</code>, <code>{`'top'`}</code>, <code>{`'top-start'`}</code>, <code>{`'bottom-end'`}</code>, <code>{`'bottom'`}</code>, <code>{`'bottom-start'`}</code>, <code>{`'right-start'`}</code>, <code>{`'right'`}</code>, <code>{`'right-end'`}</code>, <code>{`'left-start'`}</code>, <code>{`'left'`}</code>, <code>{`'left-end'`}</code></td>
128146
</tr>
129147
<tr>
130148
<td colSpan="3">
131-
<p>Describes the placement of your component after Popper.js has applied all the modifiers that may have flipped or altered the originally provided placement property.</p>
149+
<p>Determines the placement of the React Dropdown Menu after Popper.js modifiers.</p>
132150
</td>
133151
</tr>
134152
<tr id="cdropdown-popper">
@@ -138,7 +156,28 @@ import CDropdown from '@coreui/react/src/components/dropdown/CDropdown'
138156
</tr>
139157
<tr>
140158
<td colSpan="3">
141-
<p>If you want to disable dynamic positioning set this property to <code>{`true`}</code>.</p>
159+
<p>Enables or disables dynamic positioning via Popper.js for the React Dropdown Menu.</p>
160+
</td>
161+
</tr>
162+
<tr id="cdropdown-popper-config">
163+
<td className="text-primary fw-semibold">popperConfig<a href="#cdropdown-popper-config" aria-label="CDropdown popperConfig permalink" className="anchor-link after">#</a><span className="badge bg-success">5.5.0+</span></td>
164+
<td>-</td>
165+
<td><code>{`Partial\<Options>`}</code>, <code>{`((defaultPopperConfig: Partial\<Options>) => Partial\<Options>)`}</code></td>
166+
</tr>
167+
<tr>
168+
<td colSpan="3">
169+
<p>Provides a custom Popper.js configuration or a function that returns a modified Popper.js configuration for advanced positioning of the React Dropdown Menu. <a href="https://popper.js.org/docs/v2/constructors/#options">Read more</a></p>
170+
<JSXDocs code={`// Providing a custom popper config
171+
<CDropdown
172+
popperConfig={{
173+
modifiers: [
174+
{
175+
name: 'flip',
176+
options: { fallbackPlacements: ['bottom', 'top'] },
177+
},
178+
],
179+
}}
180+
>...</CDropdown>`} />
142181
</td>
143182
</tr>
144183
<tr id="cdropdown-portal">
@@ -148,7 +187,7 @@ import CDropdown from '@coreui/react/src/components/dropdown/CDropdown'
148187
</tr>
149188
<tr>
150189
<td colSpan="3">
151-
<p>Generates dropdown menu using createPortal.</p>
190+
<p>Renders the React Dropdown Menu using a React Portal, allowing it to escape the DOM hierarchy for improved positioning.</p>
152191
</td>
153192
</tr>
154193
<tr id="cdropdown-variant">
@@ -158,7 +197,7 @@ import CDropdown from '@coreui/react/src/components/dropdown/CDropdown'
158197
</tr>
159198
<tr>
160199
<td colSpan="3">
161-
<p>Set the dropdown variant to an btn-group, dropdown, input-group, and nav-item.</p>
200+
<p>Defines the visual variant of the React Dropdown</p>
162201
</td>
163202
</tr>
164203
<tr id="cdropdown-visible">
@@ -168,7 +207,17 @@ import CDropdown from '@coreui/react/src/components/dropdown/CDropdown'
168207
</tr>
169208
<tr>
170209
<td colSpan="3">
171-
<p>Toggle the visibility of dropdown menu component.</p>
210+
<p>Controls the visibility of the React Dropdown Menu:</p>
211+
<ul>
212+
<li><code>{`true`}</code> - Visible</li>
213+
<li><code>{`false`}</code> - Hidden</li>
214+
</ul>
215+
<JSXDocs code={`// Programmatically manage the dropdown visibility
216+
const [visible, setVisible] = useState(false)
217+
218+
<CDropdown visible={visible}>
219+
...
220+
</CDropdown>`} />
172221
</td>
173222
</tr>
174223
</tbody>

‎packages/docs/content/api/CPopover.api.mdx

Lines changed: 68 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ import CPopover from '@coreui/react/src/components/popover/CPopover'
2222
</tr>
2323
<tr>
2424
<td colSpan="3">
25-
<p>Apply a CSS fade transition to the popover.</p>
25+
<p>Adds a fade transition animation to the React Popover.</p>
2626
</td>
2727
</tr>
2828
<tr id="cpopover-class-name">
@@ -32,17 +32,24 @@ import CPopover from '@coreui/react/src/components/popover/CPopover'
3232
</tr>
3333
<tr>
3434
<td colSpan="3">
35-
<p>A string of all className you want applied to the component.</p>
35+
<p>Custom class name(s) for additional styling.</p>
3636
</td>
3737
</tr>
3838
<tr id="cpopover-container">
3939
<td className="text-primary fw-semibold">container<a href="#cpopover-container" aria-label="CPopover container permalink" className="anchor-link after">#</a><span className="badge bg-success">4.11.0+</span></td>
40-
<td>-</td>
40+
<td><code>{`document.body`}</code></td>
4141
<td><code>{`Element`}</code>, <code>{`DocumentFragment`}</code>, <code>{`(() => Element | DocumentFragment)`}</code></td>
4242
</tr>
4343
<tr>
4444
<td colSpan="3">
45-
<p>Appends the react popover to a specific element. You can pass an HTML element or function that returns a single element. By default <code>{`document.body`}</code>.</p>
45+
<p>Defines the container element to which the React Popover is appended.<br />
46+
Accepts:</p>
47+
<ul>
48+
<li>A DOM element (<code>{`HTMLElement`}</code> or <code>{`DocumentFragment`}</code>)</li>
49+
<li>A function that returns a single element</li>
50+
<li><code>{`null`}</code> (defaults to <code>{`document.body`}</code>)</li>
51+
</ul>
52+
<JSXDocs code={`<CPopover container={document.getElementById('my-container')}>...</CPopover>`} />
4653
</td>
4754
</tr>
4855
<tr id="cpopover-content">
@@ -52,7 +59,7 @@ import CPopover from '@coreui/react/src/components/popover/CPopover'
5259
</tr>
5360
<tr>
5461
<td colSpan="3">
55-
<p>Content node for your component.</p>
62+
<p>Main content of the React Popover. It can be a string or any valid React node.</p>
5663
</td>
5764
</tr>
5865
<tr id="cpopover-delay">
@@ -62,17 +69,26 @@ import CPopover from '@coreui/react/src/components/popover/CPopover'
6269
</tr>
6370
<tr>
6471
<td colSpan="3">
65-
<p>The delay for displaying and hiding the popover (in milliseconds). When a numerical value is provided, the delay applies to both the hide and show actions. The object structure for specifying the delay is as follows: delay: <code>{`{ 'show': 500, 'hide': 100 }`}</code>.</p>
72+
<p>Delay (in milliseconds) before showing or hiding the React Popover.</p>
73+
<ul>
74+
<li>If a number is provided, that delay applies to both "show" and "hide".</li>
75+
<li>If an object is provided, use separate values for "show" and "hide".</li>
76+
</ul>
77+
<JSXDocs code={`// Delays 300ms on both show and hide
78+
<CPopover delay={300}>...</CPopover>
79+
80+
// Delays 500ms on show and 100ms on hide
81+
<CPopover delay={{ show: 500, hide: 100 }}>...</CPopover>`} />
6682
</td>
6783
</tr>
6884
<tr id="cpopover-fallback-placements">
6985
<td className="text-primary fw-semibold">fallbackPlacements<a href="#cpopover-fallback-placements" aria-label="CPopover fallbackPlacements permalink" className="anchor-link after">#</a><span className="badge bg-success">4.9.0+</span></td>
7086
<td><code>{`['top', 'right', 'bottom', 'left']`}</code></td>
71-
<td><code>{`Placements`}</code>, <code>{`Placements[]`}</code></td>
87+
<td><code>{`'top', 'right', 'bottom', 'left'`}</code>, <code>{`('top', 'right', 'bottom', 'left')[]`}</code></td>
7288
</tr>
7389
<tr>
7490
<td colSpan="3">
75-
<p>Specify the desired order of fallback placements by providing a list of placements as an array. The placements should be prioritized based on preference.</p>
91+
<p>Specifies the fallback placements when the preferred <code>{`placement`}</code> cannot be met.</p>
7692
</td>
7793
</tr>
7894
<tr id="cpopover-offset">
@@ -82,7 +98,12 @@ import CPopover from '@coreui/react/src/components/popover/CPopover'
8298
</tr>
8399
<tr>
84100
<td colSpan="3">
85-
<p>Offset of the popover relative to its target.</p>
101+
<p>Offset of the React Popover relative to its toggle element, in the form <code>{`[x, y]`}</code>.</p>
102+
<JSXDocs code={`// Offset the menu 0px in X and 10px in Y direction
103+
<CPopover offset={[0, 10]}>...</CPopover>
104+
105+
// Offset the menu 5px in both X and Y direction
106+
<CPopover offset={[5, 5]}>...</CPopover>`} />
86107
</td>
87108
</tr>
88109
<tr id="cpopover-on-hide">
@@ -92,7 +113,7 @@ import CPopover from '@coreui/react/src/components/popover/CPopover'
92113
</tr>
93114
<tr>
94115
<td colSpan="3">
95-
<p>Callback fired when the component requests to be hidden.</p>
116+
<p>Invoked when the React Popover is about to hide.</p>
96117
</td>
97118
</tr>
98119
<tr id="cpopover-on-show">
@@ -102,7 +123,7 @@ import CPopover from '@coreui/react/src/components/popover/CPopover'
102123
</tr>
103124
<tr>
104125
<td colSpan="3">
105-
<p>Callback fired when the component requests to be shown.</p>
126+
<p>Invoked when the React Popover is about to show.</p>
106127
</td>
107128
</tr>
108129
<tr id="cpopover-placement">
@@ -112,7 +133,29 @@ import CPopover from '@coreui/react/src/components/popover/CPopover'
112133
</tr>
113134
<tr>
114135
<td colSpan="3">
115-
<p>Describes the placement of your component after Popper.js has applied all the modifiers that may have flipped or altered the originally provided placement property.</p>
136+
<p>Placement of the React Popover. Popper.js may override this based on available space.</p>
137+
</td>
138+
</tr>
139+
<tr id="cpopover-popper-config">
140+
<td className="text-primary fw-semibold">popperConfig<a href="#cpopover-popper-config" aria-label="CPopover popperConfig permalink" className="anchor-link after">#</a><span className="badge bg-success">5.5.0+</span></td>
141+
<td>-</td>
142+
<td><code>{`Partial\<Options>`}</code>, <code>{`((defaultPopperConfig: Partial\<Options>) => Partial\<Options>)`}</code></td>
143+
</tr>
144+
<tr>
145+
<td colSpan="3">
146+
<p>Allows customization of the Popper.js configuration for the React Popover.<br />
147+
Can be an object or a function returning a modified configuration.<br />
148+
<a href="https://popper.js.org/docs/v2/constructors/#options">Learn more</a></p>
149+
<JSXDocs code={`<CPopover
150+
popperConfig={(defaultConfig) => ({
151+
...defaultConfig,
152+
strategy: 'fixed',
153+
modifiers: [
154+
...defaultConfig.modifiers,
155+
{ name: 'computeStyles', options: { adaptive: false } },
156+
],
157+
})}
158+
>...</CPopover>`} />
116159
</td>
117160
</tr>
118161
<tr id="cpopover-title">
@@ -122,17 +165,22 @@ import CPopover from '@coreui/react/src/components/popover/CPopover'
122165
</tr>
123166
<tr>
124167
<td colSpan="3">
125-
<p>Title node for your component.</p>
168+
<p>Title for the React Popover header. Can be a string or any valid React node.</p>
126169
</td>
127170
</tr>
128171
<tr id="cpopover-trigger">
129172
<td className="text-primary fw-semibold">trigger<a href="#cpopover-trigger" aria-label="CPopover trigger permalink" className="anchor-link after">#</a></td>
130173
<td><code>{`click`}</code></td>
131-
<td><code>{`'hover'`}</code>, <code>{`'focus'`}</code>, <code>{`'click'`}</code></td>
174+
<td><code>{`'hover'`}</code>, <code>{`'focus'`}</code>, <code>{`'click'`}</code>, <code>{`('hover' | 'focus' | 'click')[]`}</code></td>
132175
</tr>
133176
<tr>
134177
<td colSpan="3">
135-
<p>Sets which event handlers you’d like provided to your toggle prop. You can specify one trigger or an array of them.</p>
178+
<p>Determines which events trigger the visibility of the React Popover. Can be a single trigger or an array of triggers.</p>
179+
<JSXDocs code={`// Hover-only tooltip
180+
<CPopover trigger="hover">...</CPopover>
181+
182+
// Hover + click combined
183+
<CPopover trigger={['hover', 'click']}>...</CPopover>`} />
136184
</td>
137185
</tr>
138186
<tr id="cpopover-visible">
@@ -142,7 +190,11 @@ import CPopover from '@coreui/react/src/components/popover/CPopover'
142190
</tr>
143191
<tr>
144192
<td colSpan="3">
145-
<p>Toggle the visibility of popover component.</p>
193+
<p>Controls the visibility of the React Popover.</p>
194+
<ul>
195+
<li><code>{`true`}</code> shows the popover.</li>
196+
<li><code>{`false`}</code> hides the popover.</li>
197+
</ul>
146198
</td>
147199
</tr>
148200
</tbody>

‎packages/docs/content/api/CTooltip.api.mdx

Lines changed: 64 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ import CTooltip from '@coreui/react/src/components/tooltip/CTooltip'
2222
</tr>
2323
<tr>
2424
<td colSpan="3">
25-
<p>Apply a CSS fade transition to the tooltip.</p>
25+
<p>Enables or disables the CSS fade transition for the React Tooltip.</p>
2626
</td>
2727
</tr>
2828
<tr id="ctooltip-class-name">
@@ -32,17 +32,23 @@ import CTooltip from '@coreui/react/src/components/tooltip/CTooltip'
3232
</tr>
3333
<tr>
3434
<td colSpan="3">
35-
<p>A string of all className you want applied to the component.</p>
35+
<p>Adds a custom class name to the React Tooltip container. Useful for overriding default styles or applying additional design choices.</p>
3636
</td>
3737
</tr>
3838
<tr id="ctooltip-container">
3939
<td className="text-primary fw-semibold">container<a href="#ctooltip-container" aria-label="CTooltip container permalink" className="anchor-link after">#</a><span className="badge bg-success">4.11.0+</span></td>
40-
<td>-</td>
40+
<td><code>{`document.body`}</code></td>
4141
<td><code>{`Element`}</code>, <code>{`DocumentFragment`}</code>, <code>{`(() => Element | DocumentFragment)`}</code></td>
4242
</tr>
4343
<tr>
4444
<td colSpan="3">
45-
<p>Appends the react tooltip to a specific element. You can pass an HTML element or function that returns a single element. By default <code>{`document.body`}</code>.</p>
45+
<p>Appends the React Tooltip to a specific element instead of the default <code>{`document.body`}</code>. You may pass:</p>
46+
<ul>
47+
<li>A DOM element (<code>{`HTMLElement`}</code> or <code>{`DocumentFragment`}</code>)</li>
48+
<li>A function that returns a single element</li>
49+
<li><code>{`null`}</code></li>
50+
</ul>
51+
<JSXDocs code={`<CTooltip container={document.getElementById('my-container')}>...</CTooltip>`} />
4652
</td>
4753
</tr>
4854
<tr id="ctooltip-content">
@@ -52,7 +58,7 @@ import CTooltip from '@coreui/react/src/components/tooltip/CTooltip'
5258
</tr>
5359
<tr>
5460
<td colSpan="3">
55-
<p>Content node for your component.</p>
61+
<p>Content to be displayed within the React Tooltip. Can be a string or any valid React node.</p>
5662
</td>
5763
</tr>
5864
<tr id="ctooltip-delay">
@@ -62,17 +68,26 @@ import CTooltip from '@coreui/react/src/components/tooltip/CTooltip'
6268
</tr>
6369
<tr>
6470
<td colSpan="3">
65-
<p>The delay for displaying and hiding the tooltip (in milliseconds). When a numerical value is provided, the delay applies to both the hide and show actions. The object structure for specifying the delay is as follows: delay: <code>{`{ 'show': 500, 'hide': 100 }`}</code>.</p>
71+
<p>The delay (in milliseconds) before showing or hiding the React Tooltip.</p>
72+
<ul>
73+
<li>If provided as a number, the delay is applied to both "show" and "hide".</li>
74+
<li>If provided as an object, it should have distinct "show" and "hide" values.</li>
75+
</ul>
76+
<JSXDocs code={`// Delays 300ms on both show and hide
77+
<CTooltip delay={300}>...</CTooltip>
78+
79+
// Delays 500ms on show and 100ms on hide
80+
<CTooltip delay={{ show: 500, hide: 100 }}>...</CTooltip>`} />
6681
</td>
6782
</tr>
6883
<tr id="ctooltip-fallback-placements">
6984
<td className="text-primary fw-semibold">fallbackPlacements<a href="#ctooltip-fallback-placements" aria-label="CTooltip fallbackPlacements permalink" className="anchor-link after">#</a><span className="badge bg-success">4.9.0+</span></td>
7085
<td><code>{`['top', 'right', 'bottom', 'left']`}</code></td>
71-
<td><code>{`Placements`}</code>, <code>{`Placements[]`}</code></td>
86+
<td><code>{`'top', 'right', 'bottom', 'left'`}</code>, <code>{`('top', 'right', 'bottom', 'left')[]`}</code></td>
7287
</tr>
7388
<tr>
7489
<td colSpan="3">
75-
<p>Specify the desired order of fallback placements by providing a list of placements as an array. The placements should be prioritized based on preference.</p>
90+
<p>Array of fallback placements for the React Tooltip to use when the preferred placement cannot be achieved. These placements are tried in order.</p>
7691
</td>
7792
</tr>
7893
<tr id="ctooltip-offset">
@@ -82,7 +97,12 @@ import CTooltip from '@coreui/react/src/components/tooltip/CTooltip'
8297
</tr>
8398
<tr>
8499
<td colSpan="3">
85-
<p>Offset of the tooltip relative to its target.</p>
100+
<p>Adjusts the offset of the React Tooltip relative to its target. Expects a tuple <code>{`[x-axis, y-axis]`}</code>.</p>
101+
<JSXDocs code={`// Offset the menu 0px in X and 10px in Y direction
102+
<CTooltip offset={[0, 10]}>...</CTooltip>
103+
104+
// Offset the menu 5px in both X and Y direction
105+
<CTooltip offset={[5, 5]}>...</CTooltip>`} />
86106
</td>
87107
</tr>
88108
<tr id="ctooltip-on-hide">
@@ -92,7 +112,7 @@ import CTooltip from '@coreui/react/src/components/tooltip/CTooltip'
92112
</tr>
93113
<tr>
94114
<td colSpan="3">
95-
<p>Callback fired when the component requests to be hidden.</p>
115+
<p>Callback fired immediately after the React Tooltip is hidden.</p>
96116
</td>
97117
</tr>
98118
<tr id="ctooltip-on-show">
@@ -102,7 +122,7 @@ import CTooltip from '@coreui/react/src/components/tooltip/CTooltip'
102122
</tr>
103123
<tr>
104124
<td colSpan="3">
105-
<p>Callback fired when the component requests to be shown.</p>
125+
<p>Callback fired immediately after the React Tooltip is shown.</p>
106126
</td>
107127
</tr>
108128
<tr id="ctooltip-placement">
@@ -112,17 +132,42 @@ import CTooltip from '@coreui/react/src/components/tooltip/CTooltip'
112132
</tr>
113133
<tr>
114134
<td colSpan="3">
115-
<p>Describes the placement of your component after Popper.js has applied all the modifiers that may have flipped or altered the originally provided placement property.</p>
135+
<p>Initial placement of the React Tooltip. Note that Popper.js modifiers may alter this placement automatically if there's insufficient space in the chosen position.</p>
136+
</td>
137+
</tr>
138+
<tr id="ctooltip-popper-config">
139+
<td className="text-primary fw-semibold">popperConfig<a href="#ctooltip-popper-config" aria-label="CTooltip popperConfig permalink" className="anchor-link after">#</a><span className="badge bg-success">5.5.0+</span></td>
140+
<td>-</td>
141+
<td><code>{`Partial\<Options>`}</code>, <code>{`((defaultPopperConfig: Partial\<Options>) => Partial\<Options>)`}</code></td>
142+
</tr>
143+
<tr>
144+
<td colSpan="3">
145+
<p>Customize the Popper.js configuration used to position the React Tooltip. Pass either an object or a function returning a modified config. <a href="https://popper.js.org/docs/v2/constructors/#options">Learn more</a></p>
146+
<JSXDocs code={`<CTooltip
147+
popperConfig={(defaultConfig) => ({
148+
...defaultConfig,
149+
strategy: 'fixed',
150+
modifiers: [
151+
...defaultConfig.modifiers,
152+
{ name: 'computeStyles', options: { adaptive: false } },
153+
],
154+
})}
155+
>...</CTooltip>`} />
116156
</td>
117157
</tr>
118158
<tr id="ctooltip-trigger">
119159
<td className="text-primary fw-semibold">trigger<a href="#ctooltip-trigger" aria-label="CTooltip trigger permalink" className="anchor-link after">#</a></td>
120160
<td><code>{`['hover', 'focus']`}</code></td>
121-
<td><code>{`'hover'`}</code>, <code>{`'focus'`}</code>, <code>{`'click'`}</code></td>
161+
<td><code>{`'hover'`}</code>, <code>{`'focus'`}</code>, <code>{`'click'`}</code>, <code>{`('hover' | 'focus' | 'click')[]`}</code></td>
122162
</tr>
123163
<tr>
124164
<td colSpan="3">
125-
<p>Sets which event handlers you’d like provided to your toggle prop. You can specify one trigger or an array of them.</p>
165+
<p>Determines the events that toggle the visibility of the React Tooltip. Can be a single trigger or an array of triggers.</p>
166+
<JSXDocs code={`// Hover-only tooltip
167+
<CTooltip trigger="hover">...</CTooltip>
168+
169+
// Hover + click combined
170+
<CTooltip trigger={['hover', 'click']}>...</CTooltip>`} />
126171
</td>
127172
</tr>
128173
<tr id="ctooltip-visible">
@@ -132,7 +177,11 @@ import CTooltip from '@coreui/react/src/components/tooltip/CTooltip'
132177
</tr>
133178
<tr>
134179
<td colSpan="3">
135-
<p>Toggle the visibility of tooltip component.</p>
180+
<p>Controls the visibility of the React Tooltip.</p>
181+
<ul>
182+
<li><code>{`true`}</code> to show the tooltip.</li>
183+
<li><code>{`false`}</code> to hide the tooltip.</li>
184+
</ul>
136185
</td>
137186
</tr>
138187
</tbody>

‎packages/docs/content/components/tooltip/index.mdx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ Hover over the links below to see tooltips:
1818

1919
You can customize the appearance of tooltips using [CSS variables](./styling/#css-variables). We set a custom `style` to scope our custom appearance and use it to override some of the local CSS variables.
2020

21+
<ExampleSnippet className="text-body-secondary" component="TooltipCustomExample" componentName="React Tooltip" />
22+
2123
### Directions
2224

2325
Hover over the buttons below to see the four tooltips directions: top, right, bottom, and left. Directions are mirrored when using CoreUI in RTL.

0 commit comments

Comments
 (0)
Please sign in to comment.