feat(CDropdown): add reference prop for custom positioning targets

Author: mrholek

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

@@ -21,7 +21,7 @@ import type { Placements } from '../../types'
 import { getNextActiveElement, isRTL } from '../../utils'
 
 import type { Alignments, Directions } from './types'
-import { getPlacement } from './utils'
+import { getPlacement, getReferenceElement } from './utils'
 import { CFocusTrap } from '../focus-trap'
 
 export interface CDropdownProps extends HTMLAttributes<HTMLDivElement | HTMLLIElement> {
@@ -161,6 +161,27 @@ export interface CDropdownProps extends HTMLAttributes<HTMLDivElement | HTMLLIEl
    */
   portal?: boolean
 
+  /**
+   * Sets the reference element for positioning the React Dropdown Menu.
+   * - `toggle` - The React Dropdown Toggle button (default).
+   * - `parent` - The React Dropdown wrapper element.
+   * - `HTMLElement` - A custom HTML element.
+   * - `React.RefObject` - A custom reference element.
+   *
+   * @example
+   * // Use the parent element as reference for positioning
+   * <CDropdown reference="parent">
+   *   <CDropdownToggle>Toggle dropdown</CDropdownToggle>
+   *   <CDropdownMenu>
+   *     <CDropdownItem>Action</CDropdownItem>
+   *     <CDropdownItem>Another Action</CDropdownItem>
+   *   </CDropdownMenu>
+   * </CDropdown>
+   *
+   * @since 5.9.0
+   */
+  reference?: 'parent' | 'toggle' | HTMLElement | React.RefObject<HTMLElement | null>
+
   /**
    * Defines the visual variant of the React Dropdown
    */
@@ -204,6 +225,7 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
       popper = true,
       popperConfig,
       portal = false,
+      reference = 'toggle',
       variant = 'btn-group',
       visible = false,
       ...rest
@@ -255,12 +277,12 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
     }, [visible])
 
     useEffect(() => {
-      const toggleElement = dropdownToggleElement
+      const referenceElement = getReferenceElement(reference, dropdownToggleElement, dropdownRef)
       const menuElement = dropdownMenuRef.current
-      if (allowPopperUse && menuElement && toggleElement && _visible) {
-        initPopper(toggleElement, menuElement, computedPopperConfig)
+      if (allowPopperUse && menuElement && referenceElement && _visible) {
+        initPopper(referenceElement, menuElement, computedPopperConfig)
       }
-    }, [dropdownToggleElement])
+    }, [dropdownToggleElement, reference])
 
     useEffect(() => {
       if (pendingKeyDownEvent !== null) {
@@ -272,21 +294,21 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
     const handleHide = useCallback(() => {
       setVisible(false)
 
-      const toggleElement = dropdownToggleElement
       const menuElement = dropdownMenuRef.current
+      const toggleElement = dropdownToggleElement
 
       if (allowPopperUse) {
         destroyPopper()
       }
 
-      toggleElement?.removeEventListener('keydown', handleKeydown)
       menuElement?.removeEventListener('keydown', handleKeydown)
+      toggleElement?.removeEventListener('keydown', handleKeydown)
 
       window.removeEventListener('click', handleClick)
       window.removeEventListener('keyup', handleKeyup)
 
       onHide?.()
-    }, [dropdownToggleElement, allowPopperUse, destroyPopper, onHide])
+    }, [allowPopperUse, dropdownToggleElement, destroyPopper, onHide])
 
     const handleKeydown = useCallback((event: KeyboardEvent) => {
       if (!dropdownMenuRef.current) {
@@ -316,7 +338,7 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
           dropdownToggleElement?.focus()
         }
       },
-      [autoClose, handleHide]
+      [autoClose, dropdownToggleElement, handleHide]
     )
 
     const handleClick = useCallback(
@@ -357,14 +379,15 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
 
     const handleShow = useCallback(
       (event?: KeyboardEvent) => {
-        const toggleElement = dropdownToggleElement
         const menuElement = dropdownMenuRef.current
+        const referenceElement = getReferenceElement(reference, dropdownToggleElement, dropdownRef)
+        const toggleElement = dropdownToggleElement
 
-        if (toggleElement && menuElement) {
+        if (menuElement && referenceElement && toggleElement) {
           setVisible(true)
 
           if (allowPopperUse) {
-            initPopper(toggleElement, menuElement, computedPopperConfig)
+            initPopper(referenceElement, menuElement, computedPopperConfig)
           }
 
           toggleElement.focus()
@@ -382,13 +405,14 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
         }
       },
       [
-        dropdownToggleElement,
         allowPopperUse,
-        initPopper,
         computedPopperConfig,
+        dropdownToggleElement,
+        reference,
         handleClick,
         handleKeydown,
         handleKeyup,
+        initPopper,
         onShow,
       ]
     )

packages/coreui-react/src/components/dropdown/utils.ts

@@ -1,3 +1,4 @@
+import React from 'react'
 import type { Placement } from '@popperjs/core'
 import type { Placements } from '../../types'
 import type { Alignments, Breakpoints } from './types'
@@ -49,3 +50,23 @@ export const getPlacement = (
 
   return _placement
 }
+
+export const getReferenceElement = (
+  reference: 'parent' | 'toggle' | React.RefObject<HTMLElement | null> | HTMLElement,
+  dropdownToggleElement: HTMLElement | null,
+  dropdownRef: React.RefObject<HTMLElement | null>
+): HTMLElement | null => {
+  if (reference === 'parent') {
+    return dropdownRef.current
+  }
+
+  if (reference instanceof HTMLElement) {
+    return reference
+  }
+
+  if (reference instanceof Object && 'current' in reference) {
+    return reference.current
+  }
+
+  return dropdownToggleElement
+}

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

@@ -190,6 +190,30 @@ const myContainer = document.getElementById('my-container')
           <p>Renders the React Dropdown Menu using a React Portal, allowing it to escape the DOM hierarchy for improved positioning.</p>
         </td>
       </tr>
+      <tr id="cdropdown-reference">
+        <td className="text-primary fw-semibold">reference<a href="#cdropdown-reference" aria-label="CDropdown reference permalink" className="anchor-link after">#</a><span className="badge bg-success">5.9.0+</span></td>
+        <td><code>{`toggle`}</code></td>
+        <td><code>{`HTMLElement`}</code>, <code>{`'parent'`}</code>, <code>{`'toggle'`}</code>, <code>{`RefObject\<HTMLElement>`}</code></td>
+      </tr>
+      <tr>
+        <td colSpan="3">
+          <p>Sets the reference element for positioning the React Dropdown Menu.</p>
+<ul>
+<li><code>{`toggle`}</code> - The React Dropdown Toggle button (default).</li>
+<li><code>{`parent`}</code> - The React Dropdown wrapper element.</li>
+<li><code>{`HTMLElement`}</code> - A custom HTML element.</li>
+<li><code>{`React.RefObject`}</code> - A custom reference element.</li>
+</ul>
+        <JSXDocs code={`// Use the parent element as reference for positioning
+<CDropdown reference="parent">
+  <CDropdownToggle>Toggle dropdown</CDropdownToggle>
+  <CDropdownMenu>
+    <CDropdownItem>Action</CDropdownItem>
+    <CDropdownItem>Another Action</CDropdownItem>
+  </CDropdownMenu>
+</CDropdown>`} />
+        </td>
+      </tr>
       <tr id="cdropdown-variant">
         <td className="text-primary fw-semibold">variant<a href="#cdropdown-variant" aria-label="CDropdown variant permalink" className="anchor-link after">#</a></td>
         <td><code>{`btn-group`}</code></td>

packages/docs/content/components/dropdown/examples/DropdownOptionsExample.tsx

@@ -1,5 +1,5 @@
 import React from 'react'
-import { CDropdown, CDropdownItem, CDropdownMenu, CDropdownToggle } from '@coreui/react'
+import { CButton, CDropdown, CDropdownItem, CDropdownMenu, CDropdownToggle } from '@coreui/react'
 
 export const DropdownOptionsExample = () => {
   return (
@@ -12,7 +12,7 @@ export const DropdownOptionsExample = () => {
           <CDropdownItem href="#">Something else here</CDropdownItem>
         </CDropdownMenu>
       </CDropdown>
-      <CDropdown portal variant="input-group">
+      <CDropdown portal>
         <CDropdownToggle color="secondary" aria-controls="dropdownMenuInPortal">
           Portal
         </CDropdownToggle>
@@ -22,6 +22,15 @@ export const DropdownOptionsExample = () => {
           <CDropdownItem href="#">Something else here</CDropdownItem>
         </CDropdownMenu>
       </CDropdown>
+      <CDropdown reference="parent">
+        <CButton color="secondary">Reference</CButton>
+        <CDropdownToggle color="secondary" split />
+        <CDropdownMenu>
+          <CDropdownItem href="#">Action</CDropdownItem>
+          <CDropdownItem href="#">Another action</CDropdownItem>
+          <CDropdownItem href="#">Something else here</CDropdownItem>
+        </CDropdownMenu>
+      </CDropdown>
     </div>
   )
 }