Backward Compatibility Notes for DropdownMenu – v1.7.0

Overview

In version 1.7.0 of the Force-UI component library, the DropdownMenu component has been improved with the addition of a new sub-component: DropdownMenu.ContentWrapper. This update is designed to make it easier to use dropdowns within Dialog, Drawer, and Popover contexts without manually managing portals.

This document highlights the change, its impact on existing usage, and instructions for migrating to the new structure.

---

🔧 What Changed

Component	Type	Description
DropdownMenu.ContentWrapper	Addition	New sub-component added to simplify dropdown integration within modal-like contexts
DropdownMenu.Portal	Adjustment	Now optional in most cases; previously always required to wrap dropdown content

---

📣 Impact on Existing Usage

If your implementation currently wraps the dropdown content in DropdownMenu.Portal, it might still work, but it's no longer required in contexts like Dialogs, Drawers, or Popovers. Continuing to use Portal in these cases may lead to visual issues such as the dropdown not being visible due to z-index or stacking problems. Also, DropdownMenu.ContentWrapper is required for the DropdownMenu component to work.

---

🧠 Migration Guide

✅ Old Implementation (Before v1.7.0)

<DropdownMenu {...some other props}>
  <DropdownMenu.Trigger {...some other props}>
    <Button>Dropdown</Button>
  </DropdownMenu.Trigger>
  <DropdownMenu.Portal {...some other props}>
    <DropdownMenu.Content className="w-60" {...some other props}>
      <DropdownMenu.List {...some other props}>
        <DropdownMenu.Item {...some other props}>Menu Item 1</DropdownMenu.Item>
        ...more items
      </DropdownMenu.List>
    </DropdownMenu.Content>
  </DropdownMenu.Portal>
</DropdownMenu>

✅ New Implementation (Without Portal) (v1.7.0 and above)

<DropdownMenu {...some other props}>
  <DropdownMenu.Trigger {...some other props}>
    <Button>Dropdown</Button>
  </DropdownMenu.Trigger>
   <DropdownMenu.ContentWrapper {...some other props}>
     <DropdownMenu.Content className="w-60" {...some other props}>
       <DropdownMenu.List {...some other props}>
         <DropdownMenu.Item {...some other props}>Menu Item 1</DropdownMenu.Item>
         ...more items
       </DropdownMenu.List>
     </DropdownMenu.Content>
   </DropdownMenu.ContentWrapper>
</DropdownMenu>

✅ New Implementation (With Portal) (v1.7.0 and above)

<DropdownMenu {...some other props}>
  <DropdownMenu.Trigger {...some other props}>
    <Button>Dropdown</Button>
  </DropdownMenu.Trigger>
  { /* The use of Portal is optional. Use it whenever required. */ }
  <DropdownMenu.Portal {...some other props}>
   <DropdownMenu.ContentWrapper {...some other props}>
     <DropdownMenu.Content className="w-60" {...some other props}>
       <DropdownMenu.List {...some other props}>
         <DropdownMenu.Item {...some other props}>Menu Item 1</DropdownMenu.Item>
         ...more items
       </DropdownMenu.List>
     </DropdownMenu.Content>
   </DropdownMenu.ContentWrapper>
  </DropdownMenu.Portal>
</DropdownMenu>

---

❓ When to Use DropdownMenu.Portal

You should still use DropdownMenu.Portal in cases where:

• The dropdown menu is cut off by a parent container, e.g., overflow: hidden
• You need to render the menu to a specific location in the DOM outside the default stacking context

Notes:

• Use DropdownMenu.ContentWrapper to make the existing implementation work. Check the above code example for the usage.
• Avoid using DropdownMenu.Portal inside Dialogs, Drawers, or Popovers (if you are facing z-index issue).
• If you're using Portal and face z-index issues, consider raising the z-index of the dropdown content manually.

---

📝 Summary

• DropdownMenu.ContentWrapper is now the recommended and required default for dropdown content wrapping.
• Use DropdownMenu.Portal only when necessary.
• The new structure improves flexibility and reduces layout bugs in nested modal or drawer contexts.

For further help, contact the Force-UI maintainers or check the component changelog.