Skip to content

Blueprint 5.0

Adi Dahiya edited this page Jul 6, 2023 · 25 revisions

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

@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)
Clone this wiki locally