Popover2 migration

Popovers in Blueprint v4.0 feature some breaking changes compared to v3.0. To help you migrate to the new component, we've provided a new component called Popover2 in a new @blueprintjs/popover2 package compatible with v3.x.

@blueprintjs/popover2 Requirements

• @blueprintjs/popover2 depends on React 16.8+. This is a stricter requirement than @blueprintjs/core.
• This package also depends on v2.x of the @popperjs/core and react-popper libraries, while the core package depends on v1.x. Note that this means you will have two versions of Popper.js installed and possibly bundled into your application at runtime.

If you are going straight to @blueprintjs/core v4.0:

Note that in addition to the changes listed below, the Popover component in v4.0 also uses the new ResizeSensor implementation, which has some breaking changes which apply to the child of Popover as well. See ResizeSensor 4.0 changes.

Notable changes compared to <Popover>:

• Positioning may be specified with either the position prop or the new placement prop. The latter maps directly to the Popper.js placement options.
  • "placement" is similar to "position", with a direct mapping that involves changing some keywords if you are using the more advanced placement options.
  • @blueprintjs/core v3.38.0+ includes support for <Popover placement> and <Tooltip placement>, so you may choose to try out the new prop semantics before migrating to Popover2, if you wish.
• There is no more .bp3-popover-wrapper wrapper element surrounding the target and overlay. This was a long-requested enhancement to the component DOM structure, as it makes styling the component and its children easier.
  • You may have to remove some redundant/excess styles which targeted the old DOM structure.
  • With usePortal={true}, just the target is rendered in place (overlay is rendered in a portal).
  • With usePortal={false}, both the target and overlay are rendered out to the DOM as siblings.

- <span class="bp3-popover-wrapper">
-     <span class="bp3-popover-target">
-         <button type="button" class="bp3-button bp3-intent-primary">
-             <span class="bp3-button-text">Popover target</span>
-         </button>
-     </span>
-     <div class="bp3-overlay bp3-overlay-inline foo"></div>
- </span>
+ <span class="bp3-popover2-target">
+     <button type="button" class="bp3-button bp3-intent-primary">
+         <span class="bp3-button-text">Popover target</span>
+     </button>
+ </span>
+ <div class="bp3-overlay bp3-overlay-inline foo"></div>

• The removal of the wrapper element means that the className prop now gets applied directly to the rendered target (before, it was applied to the wrapper element). This is equivalent to what targetClassName did before, so that that redundant prop has been removed.

• There is an option to no longer render a .bp3-popover-target wrapper element surrounding the target as well. If renderTarget prop is supplied, its return value will be rendered out directly to the DOM without a wrapper.

  • When using the renderTarget API, you must take care to render a component which propagates HTML props to its rendered children, since the render props supplied to you (including className, event handlers, etc.) are necessary for the Popover2 to function. See the "Structure" section of the docs for more info.
  • Note: in this case it is the consumer's responsibility to disable a <Tooltip2> target which is a direct child of a <Popover2> when the popover is open (<Popover> would handle this automatically for you, with its wrapper element behavior).

- <span class="bp3-popover-target">
-     <button type="button" class="bp3-button">
-         <span class="bp3-button-text">Target</span>
-     </button>
- </span>
+ <button type="button" class="bp3-button">
+     <span class="bp3-button-text">Target</span>
+ </button>

• The old API of supplying two children to <Popover>, where the first is the target and the second is the content, has been removed. Please switch to specifying content with the content prop.
• The old API of supplying a target as the first child of <Popover2> is still available. In this case, a .bp3-popover-target wrapper element will be generated around the target child, so that Blueprint can attach event handlers to it.
• For certain prop configurations (openOnTargetFocus={true} and hover interaction kinds), a tabIndex was previously generated and applied to the cloned props.children element directly. Now, that tabIndex is applied to the bp3-popover2-target wrapper element to increase the chance of this feature working in more situations.

- <span class="bp3-popover-target">
-     <button type="button" class="bp3-button" tabIndex="0">
+ <span class="bp3-popover-target" tabIndex="0">
+     <button type="button" class="bp3-button">
         <span class="bp3-button-text">Target</span>
     </button>
 </span>

• The boundary prop has changed types to match popper.js' definition of what a "boundary" is. Existing boundary configurations which actually specify a "root boundary" ("viewport" or "document") must now be specified using rootBoundary:

- boundary="viewport"
+ rootBoundary="viewport"

- boundary="window"
+ rootBoundary="document"

• The portalClassName prop behavior has changed to better match its intent. It now applies the class to the Portal container element rather than the Overlay rendered by Popover2 / Tooltip2. See #4511.