Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@atlaskit/popup

atlassian144.4kApache-2.04.2.0TypeScript support: included

A popup displays brief content in an overlay.

atlaskit, react, ui

readme

popup

A popup displays brief content in an overlay.

Installation

yarn add @atlaskit/popup

Usage

Detailed docs and example usage can be found here.

changelog

@atlaskit/popup

4.2.0

Minor Changes

  • #154745 7618d9837e247 - Tidy up design-system-closed-all-when-click-outside and sibling-dropdown-close-issue to provide better keyboard navigation.

4.1.0

Minor Changes

  • #142168 92095a01848e7 - The bounded style overrides prop (xcss) now supports logical longhand properties for padding.

4.0.0

Major Changes

  • #137034 a832dd489aab3 - - 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.

    • Added a className prop for applying a focus ring to the custom popup container (Currently controlled by the feature flag platform-design-system-apply-popup-wrapper-focus). See usage example here.

    Please note, in order to use this version of @atlaskit/popup, 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 understand how to handle .css imports. For more information on the migration, please refer to RFC-73 Migrating our components to Compiled CSS-in-JS.

Patch Changes

  • Updated dependencies

3.0.1

Patch Changes

  • #134955 ba294ad0536de - An onClose listener is being provided to the experimental open layer observer.
  • Updated dependencies

3.0.0

Major Changes

  • #127309 42392c8a66f3d - The onClose prop type has been updated, to make the first argument nullable. This argument is for the corresponding event that led to the callback being called.

    This is to support programatically closing the popup.

    Previously, the type of onClose was:

    onClose?(
     event: Event | React.MouseEvent | React.KeyboardEvent,
     currentLevel?: number | any,
    ): void;
    

    It is now:

    onClose?(
     event: Event | React.MouseEvent | React.KeyboardEvent | null,
     currentLevel?: number | any,
    ): void;

    When the popup is closed programatically, the event argument will be null.

Patch Changes

  • Updated dependencies

2.0.5

Patch Changes

2.0.4

Patch Changes

  • #129972 b2d69a39e6687 - Update @compiled/react dependency for improved type checking support.
  • Updated dependencies

2.0.3

Patch Changes

  • Updated dependencies

2.0.2

Patch Changes

2.0.1

Patch Changes

2.0.0

Major Changes

Patch Changes

  • Updated dependencies

1.32.0

Minor Changes

Patch Changes

  • Updated dependencies

1.31.3

Patch Changes

  • Updated dependencies

1.31.2

Patch Changes

  • Updated dependencies

1.31.1

Patch Changes

  • Updated dependencies

1.31.0

Minor Changes

Patch Changes

  • Updated dependencies

1.30.6

Patch Changes

1.30.5

Patch Changes

  • #103594 7b1a8574e9c29 - Fix or temporarily ignore TypeScript errors that occur in internal React 18 suites.

1.30.4

Patch Changes

  • Updated dependencies

1.30.3

Patch Changes

  • #181817 6876e5688ed14 - Dropdown open in iframe should be closed when clicking outside of the iframe

1.30.2

Patch Changes

1.30.1

Patch Changes

  • Updated dependencies

1.30.0

Minor Changes

  • #171499 397ca651978da - Adds shouldDisableGpuAcceleration prop to composable PopupContent API. This prop will configure popper.js to position the popup using only position properties, without any transform usage. This should not be used in most cases, but is needed for some layering issues.

1.29.6

Patch Changes

  • Updated dependencies

1.29.5

Patch Changes

  • Updated dependencies

1.29.4

Patch Changes

  • #165531 57f451bda8919 - Adds side-effect config to support Compiled css extraction in third-party apps

1.29.3

Patch Changes

  • Updated dependencies

1.29.2

Patch Changes

1.29.1

Patch Changes

  • Updated dependencies

1.29.0

Minor Changes

Patch Changes

  • Updated dependencies

1.28.5

Patch Changes

  • Updated dependencies

1.28.4

Patch Changes

1.28.3

Patch Changes

  • Updated dependencies

1.28.2

Patch Changes

  • Updated dependencies

1.28.1

Patch Changes

  • #148281 3c4de48168ffe - Update the import path of useId* from @atlaskit/ds-lib
  • Updated dependencies

1.28.0

Minor Changes

  • #147187 f3fc0c5bb919d - Adds usage of the useNotifyLayerObserver hook from the layering package. The hook is behind a feature flag.

Patch Changes

  • Updated dependencies

1.27.2

Patch Changes

  • Updated dependencies

1.27.1

Patch Changes

  • #144902 16cce78563062 - Fixes a bug that caused the trigger to lose the ability to have focus after closing a dropdown menu using the Escape key inside the popup content.

1.27.0

Minor Changes

  • #143323 4fdf6347eb506 - Popup and compositional popup now take an xcss prop that can adjust the popup contents padding and width.
  • #143323 4fdf6347eb506 - Popup and compositional popup now have a new appearance prop. Pass it "modal" to enable the popup to appear as a modal on small viewports.

Patch Changes

  • Updated dependencies

1.26.0

Minor Changes

  • #142538 3979d0196514a - [ux] We are testing focus ring for popup wrapper onKeyDown. Changes are implemented behind feature flag. If this fix is successful, it will be available in a later release.

1.25.0

Minor Changes

  • #138688 961d97994618c - Adds shouldFitViewport prop which will apply max-width and max-height to contain the popper/popup within the viewport.

Patch Changes

  • #138585 b72c2c7f9a2fd - Support to close all layers when clicking outside under feature flag
  • Updated dependencies

1.24.2

Patch Changes

1.24.1

Patch Changes

1.24.0

Minor Changes

1.23.2

Patch Changes

1.23.1

Patch Changes

  • #133686 462353527b0db - Expose shouldReturnFocus on Popup component to allow consumers to prevent trigger refocusing on popup close

1.23.0

Minor Changes

  • #128022 1495b8f9c9253 - [ux] We are testing new focus behavior in non-dialog popup instances behind a feature flag. With that in place, all popup instances that don't have role="dialog" applied will have focus traps disabled by default. If this fix is successful, it will be available in a later release.

1.22.2

Patch Changes

  • Updated dependencies

1.22.1

Patch Changes

  • 49e0363439f7c - [ux] Content inside of a Popup will now always have it's text color reset to color.text. Previously, the text color of Popup content would be color.text if rendering into a portal shouldRenderToParent={true} or shouldFitContainer={true}, but otherwise would inherit the text color of the parent element. We have made this change to improve consistency and avoid surprises when working with Popup.

1.22.0

Minor Changes

  • #127511 db30e29344013 - 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.3as well as to have a consistent peer dependency range forreactandreact-domfor/platform` packages.

Patch Changes

  • Updated dependencies

1.21.1

Patch Changes

  • Updated dependencies

1.21.0

Minor Changes

  • 8b8090800a35d - Bump peer dependency for react-dom to include version 17 and 18.

Patch Changes

  • Updated dependencies

1.20.3

Patch Changes

1.20.2

Patch Changes

1.20.1

Patch Changes

  • Updated dependencies

1.20.0

Minor Changes

  • #116426 d6c9799d09e87 - Updates compositional popup to take an optional prop for the popup content to expand to the full width of the parent container

1.19.4

Patch Changes

  • Updated dependencies

1.19.3

Patch Changes

  • Updated dependencies

1.19.2

Patch Changes

  • #114683 ff0815316ab38 - Removes usage of custom theme button in places where its API is not being used and the default button is able to be used instead. This should give a slight performance (runtime) improvement.

1.19.1

Patch Changes

  • Updated dependencies

1.19.0

Minor Changes

  • #110836 a8bd419fd70b9 - Explicitly set jsxRuntime to classic via pragma comments in order to avoid issues where jsxRuntime is implicitly set to automatic.

Patch Changes

  • Updated dependencies

1.18.0

Minor Changes

  • #111709 2f3d71601a7c2 - [ux] Adds a new optional shouldFitContainer prop, which when set to true, will fit the popup width to its parent's width.

Patch Changes

  • Updated dependencies

1.17.2

Patch Changes

  • Updated dependencies

1.17.1

Patch Changes

  • #97895 4f26610d9fbc - Adds auto-generated ID to popup and popup triggers for better coverage of assistive technologies and aria-controls..

1.17.0

Minor Changes

  • #91673 e757c83a22ee - Add new props for improving accessibility: role, label and titleId.

1.16.0

Minor Changes

  • #95249 039491355ada - Adds new entry points for an alternate experimental Popup API using composable components. The new exports are prefixed with UNSAFE should only be used after agreement with the Design System team.

1.15.1

Patch Changes

  • Updated dependencies

1.15.0

Minor Changes

1.14.1

Patch Changes

1.14.0

Minor Changes

  • #84410 9d5dc8f7de85 - Adds a new strategy prop to control the positioning strategy to use other than the default 'fixed' position.

1.13.2

Patch Changes

1.13.1

Patch Changes

1.13.0

Minor Changes

  • #70573 c8fa9cdd08e4 - Accessibility changes. Add a new optional prop shouldDisableFocusLock. We are testing the ability to close the popup by pressing the Tab key when shouldDisableFocusLock is true and shouldRenderToParent is true behind a feature flag. This is necessary for the dropdown menu to work correctly. If this fix is successful it will be available in a later release.

1.12.0

Minor Changes

  • #70664 776e5ba8fc41 - Enable layering in popup and dropdown to support nested navigation

1.11.6

Patch Changes

  • #67435 7949bd7f5cb6 - Support to disable pointer-events on iframe when popup is open to fix issue of clicking on iframe won't close popup

1.11.5

Patch Changes

1.11.4

Patch Changes

1.11.3

Patch Changes

  • #42594 07781d6d786 - Removes feature flag implemented in 1.11.0. Does not implement proposed functionality behind the feature flag.

1.11.2

Patch Changes

1.11.1

Patch Changes

  • #41322 f54519b315c - This removes the error in console when passing shouldRenderToParent prop.

1.11.0

Minor Changes

  • #41251 b0a2a8d78c6 - [ux] We are testing removing the focus-trap package for a smaller sharper implementation of focus management behind a feature flag. If this fix is successful it will be available in a later release.

1.10.2

Patch Changes

  • #41354 d621fe3e4f8 - fix ReferenceError where frameId is used before it is initialised

1.10.1

Patch Changes

  • #40515 a54578d2ea9 - This removes the feature flag for the shouldRenderToParent prop. The prop is available for use.

1.10.0

Minor Changes

Patch Changes

  • Updated dependencies

1.9.3

Patch Changes

  • #39278 84442a93613 - Adds support for surface detection when using design tokens. Enabling children to be styled with the surface color of the popup when using the utility.elevation.surface.current design token.
  • Updated dependencies

1.9.2

Patch Changes

  • #38011 065da872439 - Css changes for testing the feature flag platform.design-system-team.render-popup-in-parent_f73ij.

1.9.1

Patch Changes

  • #37614 6a0a3c059ba - Remove unused argument from internal focus management function.

1.9.0

Minor Changes

  • #34797 3920dcfd848 - This removes the feature flag made for upgrading the focus-trap dependency and keeps focus-trap at it's original version.

1.8.3

Patch Changes

  • #36754 4ae083a7e66 - Use @af/accessibility-testing for default jest-axe config and jest-axe import in accessibility testing.

1.8.2

Patch Changes

  • #36447 472a62ce219 - [ux] Fixes autoFocus functionality on upgrade of focus-trap to v7.

1.8.1

Patch Changes

  • #35441 599bfe90ee3 - Internal change to use shape tokens. There is no expected visual change.

1.8.0

Minor Changes

  • ac5a05f5929 - We are testing an upgrade to the focus-trap dependency behind a feature flag. If this fix is successful it will be available in a later release.

1.7.0

Minor Changes

  • #35092 eca89633804 - Add a new prop shouldRenderToParent to allow render popup into a DOM node within the parent DOM hierarchy instead of React portal.

1.6.4

Patch Changes

  • #35299 e2a6337bb05 - Reverts changes 1.6.3 in @atlaskit/popup, reverts disabling pointer events on iframes when popup is open.

1.6.3

Patch Changes

  • #34314 c394dbc632f - Addresses the problem where the popup fails to close upon clicking on the iframe

1.6.2

Patch Changes

1.6.1

Patch Changes

1.6.0

Minor Changes

Patch Changes

  • Updated dependencies

1.5.5

Patch Changes

  • Updated dependencies

1.5.4

Patch Changes

  • Updated dependencies

1.5.3

Patch Changes

  • Updated dependencies

1.5.2

Patch Changes

  • Updated dependencies

1.5.1

Patch Changes

  • #26303 9827dcb82b8 - No-op change to introduce spacing tokens to design system components.

1.5.0

Minor Changes

  • #24710 c520e306869 - Updates @emotion/core to @emotion/react; v10 to v11. There is no expected behavior change.

1.4.2

Patch Changes

1.4.1

Patch Changes

1.4.0

Minor Changes

Patch Changes

  • 8202e37941b - Internal code change turning on new linting rules.
  • Updated dependencies

1.3.10

Patch Changes

  • #22614 8a5bdb3c844 - Upgrading internal dependency (bind-event-listener) for improved internal types

1.3.9

Patch Changes

  • #21570 dcf8150c49c - Allow trigger props to be applied to any HTML element tag without causing type errors for the ref type

1.3.8

Patch Changes

  • Updated dependencies

1.3.7

Patch Changes

  • #21242 2e7bbdfd813 - Upgrading internal dependency 'bind-event-listener' to 2.1.0 for improved types

1.3.6

Patch Changes

1.3.5

Patch Changes

  • Updated dependencies

1.3.4

Patch Changes

  • Updated dependencies

1.3.3

Patch Changes

  • Updated dependencies

1.3.2

Patch Changes

  • #16752 19d72473dfb - The no-unsafe-design-token-usage eslint rule now respects the new token naming conventions when auto-fixing by correctly formatting token ids.
  • 19d72473dfb - The no-unsafe-design-token-usage eslint rule now respects the new token naming conventions when auto-fixing by correctly formatting token ids.
  • Updated dependencies

1.3.1

Patch Changes

  • Updated dependencies

1.3.0

Minor Changes

  • #17576 2e42aa0d900 - Note: It is a re-release of the wrongly patched version 1.1.6 that should have been a minor release.

    Expose fallbackPlacement modifier from to specify a list of fallback options to try incase there isn't enough space

Patch Changes

  • Updated dependencies

1.2.0

Minor Changes

  • #16960 c2dd770a743 - Add new prop which controls is outside click should be bound using capture

1.1.6

WRONG RELEASE TYPE - DON'T USE

Minor Changes

  • #15998 f142150a3e8 - Expose fallbackPlacement modifier from to specify a list of fallback options to try incase there isn't enough space

Patch Changes

  • f460cc7c411 - Builds for this package now pass through a tokens babel plugin, removing runtime invocations of the tokens() function and improving bundle size.
  • Updated dependencies

1.1.5

Patch Changes

  • Updated dependencies

1.1.4

Patch Changes

  • Updated dependencies

1.1.3

Patch Changes

  • Updated dependencies

1.1.2

Patch Changes

  • Updated dependencies

1.1.1

Patch Changes

  • Updated dependencies

1.1.0

Minor Changes

Patch Changes

  • Updated dependencies

1.0.8

Patch Changes

1.0.7

Patch Changes

1.0.6

Patch Changes

  • #6930 1858f20ac3 - Optimised popup performance as part of the lite-mode project. Changes are internal and have no implications for component API or usage.

1.0.5

Patch Changes

1.0.4

Patch Changes

  • #5497 5f58283e1f - Export types using Typescript's new "export type" syntax to satisfy Typescript's --isolatedModules compiler option. This requires version 3.8 of Typescript, read more about how we handle Typescript versions here: https://atlaskit.atlassian.com/get-started Also add typescript to devDependencies to denote version that the package was built with.

1.0.3

Patch Changes

  • Updated dependencies

1.0.2

Patch Changes

  • #4346 fc8f6e61f3 - Fix codemod utilities being exposed through the codemod cli

1.0.1

Patch Changes

  • #3885 6c525a8229 - Upgraded to TypeScript 3.9.6 and tslib to 2.0.0

    Since tslib is a dependency for all our packages we recommend that products also follow this tslib upgrade to prevent duplicates of tslib being bundled.

1.0.0

Major Changes

  • #3823 740e011f8d - This first major release of popup brings in major changes from @atlaskit/popper. These changes come with performance, maintainability and behavioral improvements.

    As popup wraps popper's functionality, these changes result in a breaking change for popup as well.

    These changes have ⚙️ codemod support:

    • ⚙️ offset is no longer a string, but an array of two integers (i.e. '0px 8px' is now [0, 8])
    • ⚙️ boundariesElement has been replaced with two props: boundary and rootBoundary. The three supported values from the boundariesElement prop have been split between the two as follows:

      • boundariesElement = "scrollParents" has been renamed: use boundary = "clippingParents".
      • boundariesElement = "window" has been renamed: use rootBoundary = "document", and acts in a similar fashion.
      • boundariesElement = "viewport" has been moved: use rootBoundary = "document".
      • ✨new the boundary prop now supports custom elements.
    • Components passed into the content have a change to render props:

      • ⚙️ scheduleUpdate, for async updates, has been renamed to update, and now returns a Promise.
    • For more information on the change, see the popper.js docs

    Running the codemod cli

    To run the codemod: You first need to have the latest version of popup installed before you can run the codemod

    yarn upgrade @atlaskit/popup@^1.0.0

    Once upgraded, use the Atlaskit codemod-cli;

    npx @atlaskit/codemod-cli --parser [PARSER] --extensions [FILE_EXTENSIONS] [TARGET_PATH]

    Or run npx @atlaskit/codemod-cli -h for more details on usage. For Atlassians, refer to this doc for more details on the codemod CLI.

Patch Changes

  • Updated dependencies

0.6.1

Patch Changes

0.6.0

Minor Changes

Patch Changes

  • Updated dependencies

0.5.0

Minor Changes

  • #3289 ebcb467688 - Add a new prop autoFocus to allow consumers to control whether the Popup takes focus when opened

0.4.3

Patch Changes

  • #2866 54a9514fcf - Build and supporting files will no longer be published to npm

0.4.2

Patch Changes

  • #2430 649f69b6d7 - Patch all packages that are used by confluence that have a broken es2019 dist

0.4.1

Patch Changes

  • #2186 f4d4de67e4 - Prevent closing of popup when clicked element (which is inside content) is removed from the DOM

0.4.0

Minor Changes

  • #2060 ead13374cf - BREAKING: Removes tag prop and unneeded wrapping element around the trigger.

0.3.5

Patch Changes

0.3.4

Patch Changes

0.3.3

Patch Changes

0.3.2

Patch Changes

0.3.1

Patch Changes

0.3.0

Minor Changes

  • [minor]0946fdd319:

    • BREAKING - Changes content prop to expect render props instead of a component. This is primarily to stop your components remounting when not having a stable reference.

0.2.7

Patch Changes

  • [patch]eb1ecc219a:

    Fix issue where stopping event propagation would still close a popup

0.2.6

Patch Changes

0.2.5

Patch Changes

0.2.4

Patch Changes

  • [patch]d0415ae306:

    Popup now uses the correct e200 shadow

0.2.3

Patch Changes

  • [patch]542080be8a:

    Bumped react-popper and resolved infinite looping refs issue, and fixed close-on-outside-click for @atlaskit/popup- [patch]995c1f6fd6:

    Popup close on outside click no longer fires when clicking on content within the popup that re-renders

0.2.2

Patch Changes

  • [patch]3cad6b0118:

    Exposed offset prop for popper allowing positioning of popups relative to the trigger. Added example for double pop-up pattern

0.2.1

Patch Changes

  • [patch]f86839ca4e:

    @atlaskit/portal had an issue in IE11 and this is fixed in 3.1.2

0.2.0

Minor Changes

  • [minor]6e0bcc75ac:

    • Adds the ability to render class components as children of Popup.
    • Removes redundatnt onOpen callback prop for Popup

0.1.5

Patch Changes

  • [patch]93fe1d6f0d:

    Fix issue where popup content is rendered infinitely

0.1.4

Patch Changes

  • [patch]c0a6abed47:

    Add onOpen and re-render unit tests

0.1.3

Patch Changes

  • [patch]28e9c65acd:

    • Add multiple popups example
    • Add unit tests
    • Add useCloseManager
    • Fix bug that did not call onClose on open popups
    • Move RepositionOnUpdate to a separate file
    • Remove scroll lock and corresponding example
    • Remove requestAnimationFrame usage
    • Replace @emotion/styled with @emotion/core

0.1.2

Patch Changes

0.1.1

Patch Changes

  • [patch]583a9873ef:

    Provided better description for popup types

0.1.0

Minor Changes

  • [minor]f1a3548732:

    Introduce new package for the lightweight inline-dialog to be used in @atlaskit/app-navigation. The package will stay internal for now until more hardening is done, but releasing first minor to unblock navigation work.