Blueprint 5.0

Blueprint 5.0 is now available (as of May 2023). It includes 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, avoiding the kinds of conflicts which made the v1 → v3 transition difficult.

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

Check out the latest documentation here →

Feature overview

• Updated popover component which has a simpler DOM structure (no more wrapper element) and uses Popper.js 2.0 for better positioning behavior (#4023).
• Icons are split into separate modules to allow tree-shaking and/or lazy-loading only the icons you use (#2193)

Breaking changes overview

Major changes

• CSS namespace changed from bp4- to bp5-
• All components which render popovers now use the updated version of <Popover> with popper.js v2.x (previously available as { Popover2 } from "@blueprintjs/popover2")
  • Breadcrumbs
  • CollapsibleList
  • ContextMenu
  • MenuItem
  • Popover
  • Tooltip
  • DateInput
  • DateRangeInput
  • MultiSelect
  • Select
  • Suggest
  • JSONFormat
  • TruncatedFormat
  • TimezonePicker (now TimezoneSelect)
• Removed support for IE11
  • You can now remove dom4 and various core-js polyfills you may have been applying to support Blueprint in IE11

Other changes

• TypeScript interfaces renamed to drop their I prefix (reasons listed here)
  • Blueprint versions released on 2021-04-19 (core v3.44.0, datetime 3.23.0, popover2 0.6.0, select 3.16.0, timezone 3.9.0) and newer contain type aliases for most interface names in the public API without the I prefix, so you may migrate to these symbols in v3.x or v4.x before going to v5.0 directly.
  • There are some minor exceptions / special cases to this, see Toaster 5.0 changes.
• <Portal> now has support for the stable React context API in addition to the legacy API. See Portal 5.0 changes.
• Simpler, more straightforward React ref APIs. The elementRef prop is be replaced by the simpler, more straightforward ref prop using React.forwardRef() (see docs). This applies to:
  • Typography HTML components (H1, H2, ... Code, Label, etc.)
  • ButtonGroup, Card, ControlGroup, Button, AnchorButton, MenuItem, HTMLSelect, HTMLTable, and Tag (these components are now function components instead of class components, which is a slight break)
• Removed usage of React.findDOMNode in Table and Draggable components (#6137)
• As a result of the <Icon> component changes, some IconProps customizations are no longer supported:
  • <HTMLSelect iconProps={{ icon }} /> is no longer available; use <HTMLSelect iconName="..." /> with one of the supported icon option values instead (available since @blueprintjs/core v4.20.0)

Removal/migration of deprecated APIs

@blueprintjs/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.
• 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.
• IConstructor is removed (deprecated since 3.43.0)
• getDisplayName is removed (deprecated since 3.43.0)
• <Icon iconSize> prop is removed (deprecated since 3.47.0)
  • Use the size prop on <Icon> instead.
• IElementRefProps is removed (deprecated since 3.43.0)
  • Components use ref prop name instead
• IRef, IRefObject, and IRefCallback types are removed
  • Use React.Ref, React.RefObject, and React.RefCallback instead
• <HTMLTable condensed> prop is removed (deprecated since 4.14.0)
  • Use <HTMLTable compact> instead
• Removed I-prefixed interfaces (IProps, IToastOptions, etc.): see full list here

@blueprintjs/datetime

• Removed I-prefixed interfaces (IDateInputProps, etc.): see full list here

@blueprintjs/docs-theme

• Removed I-prefixed interfaces (IExampleProps, IDocumentationProps, etc.): see full list here

@blueprintjs/select

• Removed I-prefixed interfaces (ICreateNewItem, IListItemsProps, etc.): see full list here

@blueprintjs/table

• Removed I-prefixed interfaces (IMenuContext, IContextMenuRenderer, IFocusedCellCoordinates, etc.): see full list here

Miscellaneous improvements & enhancements

• <ResizeSensor> now supports React strict mode, but this means it must be stricter about its children, see ResizeSensor 5.0 changes
• <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

Note: v5.0 change list was reduced in scope in August 2022, and some of the following items were punted to future major versions.

Coming in v6

• Full compatibility with React strict mode
  • Remove remaining usage of deprecated React context API in Overlay (#4149), Table, and Portal components
  • Removed remaining usage of React.findDOMNode in Overlay via react-transition-group (#3979)
• Remove remaining decorator APIs, migrate to components/hooks instead (#3604)
  • @HotkeysTarget -> <HotkeysTarget> / useHotkeys
  • N.B. @ContextMenuTarget -> <ContextMenuTarget> breaking change was already included in v5.0
• Improved <PanelStack> component API (parameterized by its panel data type) (#4272)

Unscheduled

• CSS Modules (#248)