Modal dialog

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.

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.

dec4f3444bce8, (opens new window) - Hardens Popup, Popover, and Dialog through stricter typed contracts, focus-management fixes, and clearer entry points.

• Stricter API contracts. Popup, Popover, and Dialog props are now discriminated unions, so misuse (manual mode with onClose, dialogs without a label, popovers without an accessible name for their role) fails at compile time.
• Better defaults. Popup's placement prop now defaults to "below trigger, centered, with space.100 gap", removing the awkward placement={{}} boilerplate.
• Focus-management fixes. Empty/loading dialogs no longer trap Tab on <body>; rapid open/close/open sequences no longer focus a torn-down popover; nested top-layer popovers stay in their own focus scope.
• Cleaner entry points. createCloseEvent is now available as per-primitive subpaths (@atlaskit/top-layer/dialog/create-close-event and @atlaskit/top-layer/popover/create-close-event); the combined entry point is deprecated. The placement-map entry point now exposes a public LEGACY_PLACEMENTS const for migration consumers.
• Per-primitive data attributes. Animation hooks now emit data-ds-popover-* for Popover and data-ds-dialog-* for Dialog, preventing cross-primitive selector collisions.
• Performance and internal correctness. setStyle snapshots and restores prior inline values; CSS-length resolution is memoised and probes inside the popover for correct token scope; placement resolution is stable across renders.

Updated dependencies

• Dialog registers as type: 'modal', with a no-op onClose, as there is no current use case for programmatic close of modals via the open layer observer.
• Popover registers as type: 'popup' for interactive overlay roles (dialog, alertdialog, menu, listbox, tree, grid) and omits type for other roles (e.g. tooltip).
• A new programmatic value has been added to TPopoverCloseReason to distinguish programmatic closes, such as those from the open layer observer's closeLayers() calls.

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

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

babe23b40c154, (opens new window) - Removes the boolean type for the autoFocus prop in the modal dialog. This improves the accessibility of the modal dialog by ensuring focus always moves to the first interactive element, as per the WCAG accessibility guidelines for modal dialogs.

You can run the included codemod to remove all boolean instances of autoFocus.

a6376c3a0cd91, (opens new window) - Modal body now explicitly sets the font style to use typography tokens, instead of relying on the CSS reset to be present. This change is no longer behind a feature flag.

This change was previously reverted and is being redone.

05dd9b7db95b7, (opens new window) - Modal dialog now registers with the open layer observer using the useNotifyLayerObserver hook.

This change was previously behind the feature flag platform-dst-open-layer-observer-layer-type, which has now been removed.

#128593, (opens new window) 19d6172ffdfe9, (opens new window) - Migrated from @emotion/react to @compiled/react in order to improve performance, align with the rest of the Atlaskit techstack, and support React 18 Streaming SSR. Please note, in order to use this version of @atlaskit/modal-dialog, you will need to ensure that your bundler is configured to handle .css imports correctly.

Most bundlers come with built-in support for .css imports, so you may not need to do anything. If you are using a different bundler, please refer to the documentation for that bundler to understandhow to handle .css imports. For more information on the migration, please refer to RFC-73 Migrating our components to Compiled CSS-in-JS, (opens new window).

#127054, (opens new window) fb709895d8d5c, (opens new window) - [ux] Adds a new hasCloseButton prop to ModalHeader to add a close button. This uses the exported CloseButton internally.

This is done to improve the accessibility of all modal dialogs and ensure that users of assistive technology get full context of the modal and so that pointer users have a more clear way to close the modal.

#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)

#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.

#13864, (opens new window) 07ad26948a1, (opens new window) - In this version we made modal dialog dramatically faster and lighter with a new composable API. This is a large change and we have provided a codemod to help you upgrade. Once you have run the codemod there may be manual change required so read below for all the changes in this release.

Running the codemod cli

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

Once upgraded, use @atlaskit/codemod-cli:

The CLI will show a list of components and versions so select @atlaskit/modal-dialog@^12.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, (opens new window) for more details on the codemod CLI.

The primary button in the footer is now on the right. This has changed from being on the left to match the design documentation, (opens new window).

The codemod will automatically reverse the order of your actions for this to happen. You could previously achieve this behaviour by adding an appearance key to your actions. The codemod will detect this and not reverse the array in this case.

The old version of modal dialog had three props that mapped into components.

• heading was the text for the header.
• children was the React node that ended up in the modal body.
• actions was an array of objects that mapped into buttons in the footer.

The new composable API exposes these components so that you can use them directly as a child of modal dialog. This creates a clear parallel between what is given as children and what the modal dialog renders. It also allows you to use any valid React node as a child of modal dialog.

The original children need to be wrapped in a ModalBody.

The heading prop turns into a ModalHeader and ModalTitle.

The actions prop turns into Button's in a ModalFooter.

Previously in the examples the primary button was on the left, we’ve updated the documentation to match our design documentation so that the primary button is on the right. You could previously achieve this behaviour by adding an appearance key to your actions. The codemod will reverse the order of your actions if you have not set the appearance in the actions.

The components prop has been entirely replaced with the composable API. The philosophy of creating a custom component that receive modal's props has been replaced with custom components where the user can define their own props.

To replace using the Container prop you can wrap Modal's children in the container component. Note that unless you are using a form you will need to add the style all: inherit; to ensure scrolling works.

To replace using the Header prop you can use your custom header as the first child.

If you are creating a custom header you should call the new hook useModal to get the title id so the content and the title can be linked. You can also access the onClose function this way.

If you are doing something simple like adding a button you can continue to use ModalHeader.

Similar to Header, if you were using the Footer or Body prop, you can replace ModalFooter and ModalBody with any valid React node. ModalFooter and ModalBody also accept any valid React node as children. useModal works in any of Modal's children if you wish to use it.

The scrollBehavior prop has changed from strings 'inside', 'inside-wide' and 'outside' to a boolean shouldScrollInViewport. 'inside' and 'inside-wide' have consolidated to be shouldScrollInViewport={false} and 'outside' is shouldScrollInViewport={true}.

The appearance prop has been removed from Modal and is now set on ModalTitle and the primary Button.

The isChromeless is no longer supported as you can any valid React node in Modal and choose not to use ModalHeader, ModalBody and ModalFooter. The only change to this behaviour is that there is no way to turn off the box shadow and border radius, which used to happen when isChromeless={true}. You only need to change your usage if Modal's children set their own background and don’t have a border radius of 3 px. In this case set the border radius to 3px.

The mapping for test IDs have changed.

Modal: {testId} -> {testId}

Modal content: {testId}-dialog-content -> DOM node removed

Modal header: {testId}-dialog-content--header -> {testId}--header

Modal title: {testId}-dialog-content--heading -> {testId}--title

Modal body: {testId}-dialog-content--body -> {testId}--body

Modal footer: {testId}-dialog-content--footer -> {testId}--footer

Scrollable body content: {testId}-dialog-content--scrollable -> {testId}--scrollable

Blanket: {testId}--blanket -> {testId}--blanket

Modal actions: {testId}-dialog-content--action-{index} -> Removed, can set on Button

• ModalFooter now uses flex-end instead of space-between to justify its contents.
• Inner components ModalFooter, ModalHeader and ModalBody no longer accepts style prop. If you wish to modify the styles, you have to build your own component.
• ContainerComponentProps and ScrollBehavior types are now removed with no replacements.
• (Header|Body|Footer|Title)ComponentProps types are now aliased to Modal(Header|Body|Footer|Title)Props, however most props are not used anymore as state is shared via the useModal hook.