Blueprint 4.0

Blueprint 4.0 is planned for release in March 2021. It will include fixes and improvements to the JS APIs and only minor changes to styles / CSS APIs. We are aiming to make the upgrade as smooth as possible, hopefully avoiding the kinds of conflicts which made the v1 → v3 transition difficult. Larger systemic changes to the design system may be targeted for Blueprint 5.x.

To prepare for the 4.0 release, you should check out the Migration guides linked in the wiki sidebar →

Feature overview

• Full compatibility with React strict mode
  • Removed usage of deprecated React context API (#4149)
  • Removed usage of React.findDOMNode (#3979)
• Use Popper.js 2.0 (#4023)
• No more decorator APIs, just components/hooks instead (#3604)
  • @HotkeysTarget -> <HotkeysTarget> / useHotkeys
  • @ContextMenuTarget -> <ContextMenuTarget>
• Icons split into separate modules to allow tree-shaking and/or lazy-loading only the icons you use (#2193)

Breaking changes overview

Major changes

• React 16.8+ required
• CSS namespace changed from bp3- to bp4-
• TypeScript interfaces renamed to drop their I prefix

Other changes

• Improved <PanelStack> component API (parameterized by its panel data type) (#4272)
• Simpler, more straightforward React ref APIs. elementRef prop has been replaced by the simpler, more straightforward ref prop using React.forwardRef() (see docs). This applies to:
  • Typography HTML components (H1, H2, ... Code, Label, etc.)
  • HTMLSelect, HTMLTable, and Tag (these components are also now function components instead of class components, which is a slight break)
• TypeScript consumers will need to enable allowSyntheticDefaultImports to compile Blueprint library typings

Removal/migration of deprecated APIs

core

• <CollapsibleList> is removed (deprecated since 3.0.0)
  • Use <OverflowList> instead.
• Classes.SELECT is removed (deprecated since 3.0.0)
  • Use <HTMLSelect> or Classes.HTML_SELECT instead.
• IKeyWhitelist and IKeyBlacklist are removed (deprecated since 3.30.0)
  • Use KeyAllowlist / KeyDenylist instead.
• Utils.safeInvoke and Utils.safeInvokeOrValue are removed (deprecated since 3.32.0)
  • Use TypeScript optional call operator ?.() instead (available since TS 3.7).
• Utils.createReactRef and ElementRefProps are removed (deprecated since 3.43.0)
• IDrawerProps.vertical is removed (deprecated since 3.15.0)
  • Use the position prop on <Drawer> instead.
• <HTMLTable> component small prop is removed (deprecated since 3.6.0)
  • Use the condensed prop instead.
• AbstractComponent and AbstractPureComponent are replaced by their “v2” counterparts (deprecated since 3.19.0)
  • The new implementations no longer use deprecated React lifecycle methods.
• IControlledProps2 is now ControlledProps (deprecated since 3.37.0)
  • compared to IControlledProps:
    • onChange is removed. We recommend unioning the type with (for example) Pick<React.InputHTMLAttributes<HTMLInputElement>, "onChange"> to achieve the same outcome.
• Menu.Item and Menu.Divider are removed (deprecated since 3.38.0, see #3829)
  • Use MenuItem and MenuDivider instead.

Miscellaneous improvements & enhancements

• <Popover popoverRef> prop now supports ref objects, not just ref callbacks
• ButtonProps / AnchorButtonProps now include HTML attributes for buttons, so you may create reusable components which render <Button> / <AnchorButton> and expose this props type (you no longer have to type union with React.HTMLAttributes, etc.)

Not intended for this major version

• CSS Modules (#248)
  • Will aim for 5.x release to support custom theming
• Removal of icon fonts
  • This was initially planned for 4.x and we started deprecating the icon fonts in Fall 2020. But it looks like we can continue supporting them with minimal visual breaks and maintenance cost by using the right tooling, such as this icon font generation library.