Popover2 migration

Popovers and tooltips in Blueprint v5.0 will feature some breaking changes compared to v3.0 and v4.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 and v4.x.

@blueprintjs/popover2 Requirements

• @blueprintjs/popover2 depends on React 16.8+. This is a stricter requirement than @blueprintjs/core v3.x, but the same as the v4.x requirement.
• 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 v5.0:

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

Notable changes compared to <Popover>:

Most of these changes apply to Tooltip as well. Make sure you have imported the popover2 package stylesheet at @blueprintjs/popover2/lib/css/blueprint-popover2.css. Breaking changes are emphasized with ❗.

• 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 targetProps prop has been removed. Switch to the renderTarget API if you need to customize the props/attributes on the target element.
  • Edit: this prop was restored in @blueprintjs/popover2 v1.12.0, so you should be able to continue using it with Popover2
• ❗ 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"

• ❗ Popper.js modifiers are slightly different in v2, so the modifiers prop type has changed.

  • Enabling/disabling modifiers still has the same API (e.g. modifiers={{ flip: { enabled: false }})
  • Modifier options have moved to the options property, so modifiers={{ flip: { padding: 10 }} now becomes modifiers={{ flip: { options: { padding: 10 }}}}
  • Click through to the TS type definitions for more information.

• The "boundariesElement" options for the flip and preventOverflow modifiers is no longer available; you should set the corresponding Popover2 prop instead:

  • before: modifiers={{ preventOverflow: { boundariesElement: "viewport" } }}
    • → after: rootBoundary="viewport"
  • before: modifiers={{ preventOverflow: { boundariesElement: "scrollParent" } }}
    • → after: boundary="clippingParents"
  • before: modifiers={{ preventOverflow: { boundariesElement: "window" } }}
    • → after: rootBoundary="document"
  • before: modifiers={{ preventOverflow: { boundariesElement: someHtmlElement } }}
    • → after: boundary={someHtmlElement}

• Some Popper.js modifiers & options which had to be specified explicitly with v1 are now enabled by default, so you can (and should) remove them as custom config in Popover2 or Tooltip2 props:

  • modifiers: { keepTogether: { enabled: true } }

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

• Previous CSS class names such as POPOVER_CONTENT_SIZING need to be switched to the popover2 variant (from @blueprintjs/popover2), e.g. POPOVER2_CONTENT_SIZING

v2 variants of @blueprintjs/core components

Breadcrumbs2

Migration should be an easy drop-in replacement, just import { Breadcrumbs2 } from "@blueprintjs/popover2" and remember to include blueprint-popover2.css in your application.

The type of popoverProps has changed to Popover2Props, and the wrapper element has been removed from the overflow item (shown here with collapseFrom={Boundary.START}:

<ul class="bp4-overflow-list bp4-breadcrumbs">
    <li>
-         <span class="bp4-popover-wrapper">
-             <span aria-haspopup="true" class="bp4-popover-target">
-                 <span class="bp4-breadcrumbs-collapsed"></span>
-             </span>
-         </span>
+         <span aria-haspopup="true" class="bp4-popover2-target">
+             <span class="bp4-breadcrumbs-collapsed"></span>
+         </span>
    </li>
    // ... other breadcrumbs
</ul>

MenuItem2

Migration should be an easy drop-in replacement, just import { MenuItem2 } from "@blueprintjs/popover2" and remember to include blueprint-popover2.css in your application.

MenuItem2s with submenus (those with children defined, either as JSX children or via the children={} prop) now use Popover2 to render their popovers. This means that the type of popoverProps has changed to Popover2Props, and a wrapper element has been removed from the menu item DOM:

<li class="bp4-submenu" role="none">
-     <span class="bp4-popover-wrapper">
-         <span aria-haspopup="true" class="bp4-popover-target">
-             <a role="menuitem" tabindex="0" class="bp4-menu-item">
-                 <div class="bp4-fill bp4-text-overflow-ellipsis">Settings</div>
-                 <span icon="caret-right" aria-hidden="true" class="bp4-icon bp4-icon-caret-right bp4-submenu-icon">
-                     ...
-                 </span>
-             </a>
-         </span>
-     </span>
+     <span aria-haspopup="true" class="bp4-popover2-target">
+         <a role="menuitem" tabindex="0" class="bp4-menu-item">
+             <div class="bp4-fill bp4-text-overflow-ellipsis">Settings</div>
+             <span icon="caret-right" aria-hidden="true" class="bp4-icon bp4-icon-caret-right bp4-submenu-icon">
+                 ...
+             </span>
+         </a>
+     </span>
</li>