Dropdown menu

d82e6f76528ab, (opens new window) - Add direct subpath package exports as part of the linking-platform, search, media, and design-system barrel-removal (de-barrel) migration.

These packages now expose their individual modules via explicit package.json exports subpaths so that consumers can import directly from the leaf module (e.g. @atlaskit/pkg/thing) instead of the package barrel/index. This adds new public entry points without changing or removing any existing exports, so it is a backwards-compatible additive change.

No runtime behaviour changes; this is an API-surface (entry-point) addition to support tree-shaking and to unblock removal of the barrel index files.

30d3abbf78178, (opens new window) - Fixed inappropriate aria-current on a DropdownItem when it is used as a nested submenu trigger. Previously an open submenu trigger rendered aria-current="true" (via ButtonItem's selected state), which is inaccurate for a popup trigger — its open state is already conveyed by aria-expanded. aria-current is now omitted for nested triggers, resolving misleading screen reader announcements (A11Y-29757).

This change is behind the platform_dst_dropdown_nested_trigger_aria_current feature gate.

f0bf5f838abd5, (opens new window) - Apply Volt entry-point and barrel-removal standards across these packages. Public exports now resolve directly to ./src/* implementations instead of intermediate ./src/entry-points/* re-exports.

Prefer published subpaths over the package root or internal entry-point paths:

If you imported through internal entry-point modules, switch to the public subpath:

cd097a2111788, (opens new window) - Republish packages depending on @atlaskit/react-compiler-gating so their published dependency reference is updated to the renamed @atlaskit/react-compiler-gating scope.

The earlier rename of @atlassian/react-compiler-gating to @atlaskit/react-compiler-gating only bumped the renamed package itself, so dependent packages were never republished and their published versions still referenced the old @atlassian/react-compiler-gating name, which is not available in the public npm registry. This minor bump republishes all affected packages with the corrected dependency.

f2dc9097319f0, (opens new window) - ### Dropped support for legacy Typescript 4 types. Typescript 5 is now the new minimum.

Removes the typesVersions property and dist/types-ts4.5 directory from the dist.

Types are now exclusively via the "types": "dist/types/index.d.ts" property.

7250582895c0b, (opens new window) - Top-layer adoption work behind the platform-dst-top-layer feature flag. Public adopter APIs are intentionally kept narrow while the top-layer API surface settles, with one exception called out below.

Highlights:

• Pass the full [along, away] legacy popper offset through to the new top-layer placement.offset API (via fromLegacyPlacement). Previously only the away axis was forwarded, which dropped the along offset for consumers of Popup, PopupSelect, Spotlight, and Tooltip when platform-dst-top-layer is enabled.
• Fix broken import of dialogHeight and dialogWidth from the removed utils module in @atlaskit/modal-dialog.

Public API:

• @atlaskit/tooltip (minor): add an optional testId?: string field to TriggerProps. This is additive (no existing prop changes shape). Required because @atlaskit/button/new (and other Pressable-backed primitives) overwrite data-testid from spread, so the legacy (triggerProps as any)['data-testid'] workaround is silently absorbed by those consumers. A typed testId field flows through their own testId destructure instead, restoring data-testid propagation onto the rendered trigger element.
• @atlaskit/popup, @atlaskit/dropdown-menu (patch): no public type changes. Wider aria-haspopup unions that the FF-on path produces are bridged at the package boundary into @atlaskit/top-layer with localised FUDGE(top-layer-api) casts, documented in packages/design-system/top-layer/notes/decisions/migration-roadmap.md ("Open API decisions deferred to a follow-up PR"). They will be widened in a follow-up minor PR once the top-layer API is committed.
• @atlaskit/modal-dialog, @atlaskit/select, @atlaskit/spotlight (patch/minor): no public type changes; bug fixes only.

Merge-readiness fixes (FF-on test wiring + adopter behavior):

• @atlaskit/popup (minor): wire the compositional PopupContent to delegate to PopupContentTopLayer when platform-dst-top-layer is enabled. Previously only the legacy Popup component had the FF branch, leaving consumers of the compositional API on the legacy popper path.
• @atlaskit/select (minor): add an onClick handler to the PopupSelect top-layer trigger so clicks open/close the menu (mirrors the legacy global click handler in popup-select.tsx). Add explicit Escape handling on the menu's onKeyDown so the menu closes and focus returns to the trigger.
• @atlaskit/top-layer (patch): the <dialog> rendered by the Dialog primitive now sets aria-modal="true" explicitly. Modern browsers infer modal semantics from .showModal() but some assistive tech still keys off the explicit attribute.
• @atlaskit/top-layer (patch): guard use-anchor-positioning against environments where ResizeObserver is not defined (e.g. jest's node environment, used by the post-office test suite). The observer is used to wait for the popover's first valid layout before measuring; consumers in non-DOM jest environments now get a no-op observer and the scroll/resize listeners still apply if the host environment polyfills showPopover. Real browsers always have ResizeObserver.
• @atlaskit/modal-dialog (patch): on the FF-on path, drop the tabIndex={-1} (and unused :focus-visible outline) from the modal content wrapper. The native <dialog>.showModal() focus-delegate algorithm picks the first focusable descendant (including tabindex=-1), and the wrapper was hijacking initial focus from the close button. Also honor shouldReturnFocus={ref} on the FF-on path (an unmount-cleanup focuses the ref after dialog.close() so it overrides the browser's automatic return-to-trigger). Boolean shouldReturnFocus={false} is not yet honored on the FF-on path — see top-layer/notes/merge-blockers.md.
• @atlaskit/datetime-picker (patch): on the FF-on path, set mode="manual" on the Popup.Content rendered by both internal/menu-top-layer.tsx (date-picker calendar) and internal/fixed-layer-menu-top-layer.tsx (time-picker menu). With the default mode="auto", the same click event that opens the menu (which targets the react-select combobox input — outside the popover element) bubbles to the browser's native popover light-dismiss handler and immediately closes the menu. react-select / DateTimePicker already own outside-click and Esc dismissal via their own state, so opting out of the native auto-dismiss is the correct integration. Also extend the existing Esc → trigger-focus restoration in components/date-picker.tsx to the FF-on path (manual mode disables the browser's built-in focus return, and the legacy code path was already handling this for itself behind an FF negation).
• @atlaskit/popup (no public API change): no source changes — only FF-on Playwright spec/example fixes drove the suite from 21/3/2 to 27/0/0. Notable: the two test.fixme'd nested-popover cases were not browser limitations; popover="auto" chains correctly via DOM ancestry (the original fixmes had the wrong testId selector). Added testId props to two examples (16-popup-with-a11y-props, 18-should-fit-container) so default-shape tests can reach the trigger.
• Test alignment for FF-on Playwright suites across popup, select, datetime-picker, inline-dialog, inline-message, and modal-dialog: selector updates to match the new top-layer testId convention (${testId}--content, [role="dialog"][aria-label="calendar"]), per-spec skipAxeCheck() for example-level color-contrast violations unrelated to the migration, and focus assertions adjusted to match native <dialog> / Popup.Content auto-focus semantics (focus lands on the first focusable child, not the dialog container itself).
• @atlassian/capacity-planning-capacity-graph, @atlaskit/color-picker, @atlassian/timeline-table, @atlassian/global-side-navigation (patch): scope fg mocks in unit tests so platform-dst-top-layer returns false. JSDOM does not implement the native Popover API (showPopover/hidePopover/toggle events), so leaving the gate ON in unit tests caused popover content to remain in the DOM after close and broke close-behaviour assertions. Browser coverage for the FF-on path is provided by the Playwright suites listed above.
• @atlaskit/dropdown-menu (no public API change): test/example-only fixes for the FF-on Playwright suite. Added role="menuitem" to the nested-trigger ButtonItem in examples/93-testing-nested-keyboard-navigation-top-layer.tsx to satisfy axe's aria-required-children rule on the parent menu. Added a test.beforeEach(skipAxeCheck) to dropdown-menu.spec.tsx (FF-on suite) for example-level color-contrast violations on the pre-existing color.text.selected/color.background.selected token pair (3.91:1). Replaced a deadlocking await expect(moveItem).not.toBeFocused() pre-open assertion (Playwright's auto-wait blocks 5s on the absent element) with await expect(moveItem).not.toBeVisible(). Suite result: 22/22 passing.

Updated dependencies

1f9114700d351, (opens new window) - Moved new motion changes from platform-dst-motion-uplift feature gate to platform-dst-motion-uplift-popup

2bed6255731de, (opens new window) - Top-layer adoption work behind the platform-dst-top-layer feature flag. Public adopter APIs are intentionally kept narrow while the top-layer API surface settles, with one exception called out below.

Highlights:

• Pass the full [along, away] legacy popper offset through to the new top-layer placement.offset API (via fromLegacyPlacement). Previously only the away axis was forwarded, which dropped the along offset for consumers of Popup, PopupSelect, Spotlight, and Tooltip when platform-dst-top-layer is enabled.
• Fix broken import of dialogHeight and dialogWidth from the removed utils module in @atlaskit/modal-dialog.

Public API:

• @atlaskit/tooltip (minor): add an optional testId?: string field to TriggerProps. This is additive (no existing prop changes shape). Required because @atlaskit/button/new (and other Pressable-backed primitives) overwrite data-testid from spread, so the legacy (triggerProps as any)['data-testid'] workaround is silently absorbed by those consumers. A typed testId field flows through their own testId destructure instead, restoring data-testid propagation onto the rendered trigger element.
• @atlaskit/popup, @atlaskit/dropdown-menu (patch): no public type changes. Wider aria-haspopup unions that the FF-on path produces are bridged at the package boundary into @atlaskit/top-layer with localised FUDGE(top-layer-api) casts, documented in packages/design-system/top-layer/notes/decisions/migration-roadmap.md ("Open API decisions deferred to a follow-up PR"). They will be widened in a follow-up minor PR once the top-layer API is committed.
• @atlaskit/modal-dialog, @atlaskit/select, @atlaskit/spotlight (patch/minor): no public type changes; bug fixes only.

Merge-readiness fixes (FF-on test wiring + adopter behavior):

• @atlaskit/popup (minor): wire the compositional PopupContent to delegate to PopupContentTopLayer when platform-dst-top-layer is enabled. Previously only the legacy Popup component had the FF branch, leaving consumers of the compositional API on the legacy popper path.
• @atlaskit/select (minor): add an onClick handler to the PopupSelect top-layer trigger so clicks open/close the menu (mirrors the legacy global click handler in popup-select.tsx). Add explicit Escape handling on the menu's onKeyDown so the menu closes and focus returns to the trigger.
• @atlaskit/top-layer (patch): the <dialog> rendered by the Dialog primitive now sets aria-modal="true" explicitly. Modern browsers infer modal semantics from .showModal() but some assistive tech still keys off the explicit attribute.
• @atlaskit/top-layer (patch): guard use-anchor-positioning against environments where ResizeObserver is not defined (e.g. jest's node environment, used by the post-office test suite). The observer is used to wait for the popover's first valid layout before measuring; consumers in non-DOM jest environments now get a no-op observer and the scroll/resize listeners still apply if the host environment polyfills showPopover. Real browsers always have ResizeObserver.
• @atlaskit/modal-dialog (patch): on the FF-on path, drop the tabIndex={-1} (and unused :focus-visible outline) from the modal content wrapper. The native <dialog>.showModal() focus-delegate algorithm picks the first focusable descendant (including tabindex=-1), and the wrapper was hijacking initial focus from the close button. Also honor shouldReturnFocus={ref} on the FF-on path (an unmount-cleanup focuses the ref after dialog.close() so it overrides the browser's automatic return-to-trigger). Boolean shouldReturnFocus={false} is not yet honored on the FF-on path — see top-layer/notes/merge-blockers.md.
• @atlaskit/datetime-picker (patch): on the FF-on path, set mode="manual" on the Popup.Content rendered by both internal/menu-top-layer.tsx (date-picker calendar) and internal/fixed-layer-menu-top-layer.tsx (time-picker menu). With the default mode="auto", the same click event that opens the menu (which targets the react-select combobox input — outside the popover element) bubbles to the browser's native popover light-dismiss handler and immediately closes the menu. react-select / DateTimePicker already own outside-click and Esc dismissal via their own state, so opting out of the native auto-dismiss is the correct integration. Also extend the existing Esc → trigger-focus restoration in components/date-picker.tsx to the FF-on path (manual mode disables the browser's built-in focus return, and the legacy code path was already handling this for itself behind an FF negation).
• @atlaskit/popup (no public API change): no source changes — only FF-on Playwright spec/example fixes drove the suite from 21/3/2 to 27/0/0. Notable: the two test.fixme'd nested-popover cases were not browser limitations; popover="auto" chains correctly via DOM ancestry (the original fixmes had the wrong testId selector). Added testId props to two examples (16-popup-with-a11y-props, 18-should-fit-container) so default-shape tests can reach the trigger.
• Test alignment for FF-on Playwright suites across popup, select, datetime-picker, inline-dialog, inline-message, and modal-dialog: selector updates to match the new top-layer testId convention (${testId}--content, [role="dialog"][aria-label="calendar"]), per-spec skipAxeCheck() for example-level color-contrast violations unrelated to the migration, and focus assertions adjusted to match native <dialog> / Popup.Content auto-focus semantics (focus lands on the first focusable child, not the dialog container itself).
• @atlassian/capacity-planning-capacity-graph, @atlaskit/color-picker, @atlassian/timeline-table, @atlassian/global-side-navigation (patch): scope fg mocks in unit tests so platform-dst-top-layer returns false. JSDOM does not implement the native Popover API (showPopover/hidePopover/toggle events), so leaving the gate ON in unit tests caused popover content to remain in the DOM after close and broke close-behaviour assertions. Browser coverage for the FF-on path is provided by the Playwright suites listed above.
• @atlaskit/dropdown-menu (no public API change): test/example-only fixes for the FF-on Playwright suite. Added role="menuitem" to the nested-trigger ButtonItem in examples/93-testing-nested-keyboard-navigation-top-layer.tsx to satisfy axe's aria-required-children rule on the parent menu. Added a test.beforeEach(skipAxeCheck) to dropdown-menu.spec.tsx (FF-on suite) for example-level color-contrast violations on the pre-existing color.text.selected/color.background.selected token pair (3.91:1). Replaced a deadlocking await expect(moveItem).not.toBeFocused() pre-open assertion (Playwright's auto-wait blocks 5s on the absent element) with await expect(moveItem).not.toBeVisible(). Suite result: 22/22 passing.

Updated dependencies

#134856, (opens new window) 948a950e395ad, (opens new window) - The onOpenChange prop type has been updated, to make the event parameter nullable. This property is for the corresponding event that led to the callback being called.

This is to support programatically closing the dropdown menu.

We are also adding the native Event type in the type union, to better align with the underlying Popup component that DropdownMenu is built on top of.

Previously, the type of onOpenChange was:

It is now:

When the dropdown is closed programatically, the event parameter will be null.

#117363, (opens new window) 10a0f7f6c2027, (opens new window) - This package's peerDependencies have been adjusted for react and/or react-dom to reflect the status of only supporting React 18 going forward. No explicit breaking change to React support has been made in this release, but this is to signify going forward, breaking changes for React 16 or React 17 may come via non-major semver releases.

Please refer this community post for more details: https://community.developer.atlassian.com/t/rfc-78-dropping-support-for-react-16-and-rendering-in-a-react-18-concurrent-root-in-jira-and-confluence/87026, (opens new window)

#151581, (opens new window) ce972f75db165, (opens new window) - ## New Feature: Configurable Popper Strategy

Feature Overview: The @atlaskit/dropdown-menu component now includes a new strategy prop, providing developers with the ability to customize the positioning strategy of dropdowns. This enhancement offers more control over how dropdown menus are rendered and positioned, accommodating various layout needs.

Usage: The strategy prop can be set to either 'absolute' or 'fixed', with the default being 'fixed'.

• 'fixed': Positions the dropdown relative to the browser's viewport. This ensures that the dropdown remains in the same position regardless of page scrolling, making it ideal for dropdowns that need to maintain a consistent position on the screen.

• 'absolute': Positions the dropdown relative to its closest positioned ancestor, which allows the dropdown to move with the content as the page is scrolled or resized. This is useful in scenarios where the dropdown should remain contextually attached to an element within a scrollable area.

Example Usage:

Important Considerations:

• When using the shouldFitContainer prop, the strategy cannot be set to 'fixed'. In such cases, the dropdown defaults to the 'absolute' strategy to ensure proper rendering within the container.
• The strategy prop provides additional flexibility, especially in complex layouts where precise control over dropdown positioning is required. It allows the dropdown to adapt based on the surrounding context or constraints, enhancing the component's versatility.
• This feature addresses the need for more adaptable positioning strategies, allowing for better integration into varied UI designs and improving user experience by maintaining dropdown visibility and accessibility.

#127511, (opens new window) db30e29344013, (opens new window) - Widening range of react and react-dom peer dependencies from ^16.8.0 || ^17.0.0 || ~18.2.0 to the wider range of ``^16.8.0 || ^17.0.0 || ^18.0.0` (where applicable).

This change has been done to enable usage of react@18.3 as well as to have a consistent peer dependency range for react and react-dom for /platform packages.

Warning: This version is deprecated due to breaking behavioural change from removal of spread props in 11.14.5. Please upgrade to version 12.1.2 or later

#41611, (opens new window) 876d7943287, (opens new window) - Fix keyboard arrow controls for dropdown item custom component.

Warning: This version is deprecated due to breaking behavioural change from removal of spread props in 11.14.5. Please upgrade to version 12.1.2 or later

#41586, (opens new window) ef0466f92d9, (opens new window) - We are removing previously added feature flag and unsafe entry point usage of the new Button inside DropdownMenu.

Warning: This version is deprecated due to breaking behavioural change from removal of spread props in 11.14.5. Please upgrade to version 12.1.2 or later

#41355, (opens new window) cd1c813da18, (opens new window) - Menu items now have a secondary selected state (border or notch), this was previously feature flagged for Atlassian experiences and is now available for everyone.

This change makes all menu items are now relatively positioned, if you had any child elements that leaned on this behaviour your experiences will now be broken!

For example the below code code previously the div would be positioned relatively to the menu group element. Now, it is positioned relatively to the button item element.

As a path forward you should not be leaning on this behaviour. If you need a popup experience use @atlaskit/dropdown-menu or @atlaskit/popup.

Warning: This version is deprecated due to breaking behavioural change from the removal of spread props. Please downgrade to 11.14.4, or upgrade to 12.1.2 or later

#41067, (opens new window) 5a9ed67f8f5, (opens new window) - Expand rest props for more explicit function data flow.

• New usage <DropdownMenu spacing="compact" />
• The current default (can also be omitted) <DropdownMenu spacing="cozy" />

#15998, (opens new window) d65d8a545af, (opens new window) - [ux] In this version, we have significantly reduced the bundle size, improved the runtime performance and simplified the API for dropdown menu. We've also removed deprecated dependencies, which bring consistency to the spacing and padding of dropdown menu items, which may require updating VR snapshots. We've also provided codemods to help you upgrade to the latest API.

To run the codemod: You first need to have the latest version installed

yarn upgrade @atlaskit/dropdown-menu@^11.0.0

Once upgraded, use @atlaskit/codemod-cli:

npx @atlaskit/codemod-cli --parser {tsx|babylon} --extensions ts,tsx,js [relativePath]

The CLI will show a list of components and versions so select @atlaskit/dropdown-menu@11.0.0 and you will automatically be upgraded. If your usage of @atlaskit/modal-dialog cannot be upgraded a comment will be left that a manual change is required.

Run npx @atlaskit/codemod-cli -h for more details on usage. For Atlassians, refer to the documentation for more details on the codemod CLI.

• Portaling – The dropdown menu is now rendered in a React Portal and is appended at the bottom of the <body>. In most cases, this shouldn't make much of a difference. But if you have any tests that assert on DOM/React tree like snapshot tests, those will need to be updated.

• Focus lock – As the menu is not rendered next to the trigger, the focus is trapped within the menu when the menu is open.

• Layering – Another sideeffect of poratling the menu is that it is now part of the global stacking context, rather than a local stacking context. We've provided a new zIndex prop incase the layering is off.

• Title and description wrapping behaviour – Menu items which have a long title and description now wrap into multiple line by default, instead of cutting it off and showing ellipsis. You can override the default behaviour by setting shouldTitleWrap and shouldDescriptionWrap to false.

• Menu item padding – Dropdown menu items have 16px more padding horizontally.
• Removed elemAfter in group title – Icon after the group title has been removed.

Dropdown menu items no longer @atlaskit/item as the underlying component, they use @atlaskit/menu instead. This mean that some of the props that used to be spread over an Item are no longer supported. In addition to that, the following API changes have been made:

• shouldFitContainer – Deprecated. This prop has been deprecated and the codemod will remove it.
• shouldAllowMultiline – This prop has been split up into two: shouldTitleWrap and shouldDescriptionWrap. The codemod replaces its occurance with the two new ones.
• onItemActivated – The prop has been deprecated and the codemod will remove it. Use onClick instead.
• onPositionEnd – The prop has been deprecated and the codemod will remove it. Use onOpenChange instead.
• boundariesElement – The prop has been deprecated and the codemod will remove it. It is not relevant anymore as the Menu is portaled.
• isMenuFixed – The prop has been deprecated and the codemod will remove it. It is not relevant anymore as the Menu is portaled.
• position – The placement values are now consistent with Popup. They have a 1:1 mapping with the old values. The codemod maps the old values to the new.
• zIndex – The zIndex prop will need to be applied as an escape hatch in case the menu runs into any layering clashes with other elements on the screen.
• items – This prop has been deprecated because it is poor bad for performance. Pass MenuItems as children instead. The codemod removes the item prop. You’ll need to manually change it to children.
• trigger, triggerProps and triggerType – This API has been simplified the most. triggerType and triggerProps have been deprecated. trigger now accepts either a string or custom react element. If a string is passed, it is rendered as an @atlaskit/button. If a react component is passed, it is used as a trigger. Make sure to spread the provided props onto the component, they are used to position the component and provide accessibility attributes. The codemod handles the simplest case where the the triggerType is a string. For every other case, the codemod leaves a comment. Look at the section below on how it can be fixed in most cases.
• isCompact on MenuItem – The prop has been deprecated and the codemod will remove it.
• isHidden on MenuItem – The prop has been deprecated and the codemod will remove it.
• autoFocus on MenuItem – The prop has been deprecated and the codemod will remove it. Focus is directly applied to the first menu item.

• DropdownMenuStateless – DropdownMenuStateless has been deprecated. The default export DropdownMenu handles both stateless and stateful logic. The API for DropdownMenuStateless has been retained and works as expected with DropdownMenu.The codemod converts the named import into a default import.
• DropdownItemGroupCheckbox – Renamed to DropdownItemCheckboxGroup. Codemod updates the import declaration.
• DropdownItemGroupRadio – Renamed to DropdownItemRadioGroup. Codemod updates the import declaration.

Before

After