Skip to content

What's new in Blueprint 2.0

Jump to bottom
Adi Dahiya edited this page Mar 9, 2022 · 7 revisions

Blueprint 2.0

Blueprint 2.0 features JavaScript API refactors, smaller & more modular packages, and very few changes to the CSS API.

Keep reading below for the highlights, a full changelog, and a recommended migration path.

🔆 Highlights

  • The minimum version of React is now 16.2.
  • The minimum version of TypeScript for the declaration files is now 2.3.
  • Portal now uses React 16's built-in Portal functionality instead of ReactDOM.unstable_renderSubtreeIntoContainer.
  • Icon now renders SVG elements and is used in all Blueprint components.
    • This also means that you can provide your own SVG icons for all components.
    • Support for the icon font remains, but will be removed in the next major version.
  • Icon styles and fonts have moved to a new @blueprintjs/icons package
    • Core depends on this package, so you will have to import its CSS alongside blueprint.css 
    <link href="path/to/node_modules/@blueprintjs/core/lib/css/blueprint.css" rel="stylesheet" />
+ <link href="path/to/node_modules/@blueprintjs/icons/lib/css/blueprint-icons.css" rel="stylesheet" />
  • Popover2 is now the default Popover. It uses Popper.js instead of Tether, which provides much better auto-positioning capabilities and solves a number of outstanding bugs out-of-the-box.
  • All Labs components (in @blueprintjs/labs) have been moved into separate packages so that you no longer have to deal with the 0.x version range for many components that are used widely in production.

📝 Full changelog

Breaking changes are highlighted with icons:

  • 🔥 indicates new breaks that will likely require your attention during the upgrade.
    • Many of these are renames which are handled automatically by the 2.0 upgrade script.
  • ⚠️ indicates deprecations which produced warnings in Blueprint 1.x.
  • 🎨 indicates CSS layout breaks which may affect you if you have customized the styling & layout of Blueprint components directly.

All packages

  • 🔥 A small set of ES6 features are used by all Blueprint libraries: Map, Set, Array.from, Array.fill (similar to React 16 itself)
    • If you need to support older browsers that don't have these features built-in, you will need to polyfill them. See an example of this here: test-commmons/polyfill.js
  • 🔥 .css, .js, .sass, and .less files are now output in the /lib/ folder in the distributed packages instead of /dist/ (#2002)
    • Note: the web-ready bundles (e.g. core.bundle.js) for unpkg CDN consumption are still output in /dist/
  • 🔥 React component factories (DialogFactory) have been removed for all components (#1938)
  • 🔥 Support for long icon names (those prefixed with pt-icon-) has been removed in all component APIs (#2072)
    • 🛠 This refactor is handled by the upgrade script
    • SVG files in the root resources/icons/ directory have also been stripped of the pt-icon- prefix in their filenames
  • 🔥 Prop rename: iconName → icon (#2070)
    • 🛠 This refactor is handled by the upgrade script
    • icon prop now accepts JSX.Element in addition to an IconName string so you can provide your own SVG icon set
  • 🌟 Run published CSS files through postcss to remove comments and run Autoprefixer (#2241)
  • 🌟 Publish correct ES module files using new TypeScript compiler flags (#2200)
    • Enable esModuleInterop and allowSyntheticDefaultImports compiler flags to emit valid ES import statements for modules such as classnames and moment.
  • All component displayNames use Blueprint2 prefix for easier debugging (#2052)
  • Add sideEffects: "false" to package.json manifests for Webpack 4 tree-shaking support (#2051)
  • Ensure className prop is supported for all components (#1950)
  • Most enums now use string values to ease debugging (#1921)
    • in TypeScript, the enum types are still required (intent="primary" will produce a compiler error)

@blueprintjs/core

  • Publish the 2.0.0 upgrade script which renames most symbols. (#2230)
  • 📦 Dependency changes
    • 🔥 Added dependency on @blueprintjs/icons (see below)
    • 🎨 Upgrade to normalize.css v7 (#1886)
    • Upgrade to dom4 v2 (#2043)
    • Upgrade tslib (#2200)
    • Upgrade Popper.js and react-popper for latest typings (#2247)
    • Remove Sass dependency on Bourbon (#1883)
  • 🌟 Portal supports SSR now - it renders nothing on the server (#2205)
    • 🔥 the DOM element created by Portal is now treated as its root, so className is applied to this element. this also means that no dummy element is created inside the portal, making it one level shallower.
    • 🔥 Removed containerRef prop as it no longer makes sense given note above. Users can simply apply refs to the elements they render in the portal.
  • Button & ButtonGroup
    • New alignText prop and Alignment enum (#2089, #2096)
    • text now accepts React.ReactNode (any single React renderable) instead of only string (#2088)
    • 🎨 CSS refactor to use flex box (#2078)
    • 🎨 Remove dividers from minimal button groups (#2098)
  • Icon renders SVG paths
    • 🔥 Component now renders svg.pt-icon instead of span.pt-icon-standard (#2028)
    • 🔥 support for "long" icon names pt-icon-<name> has been removed; only the short <name> syntax is supported (#2072)
    • ⭐ iconName ⇒ icon and now accepts JSX.Element | IconName for custom icons (#2070)
    • standard/large size switching is now automatic based on iconSize prop value
      • Constants are provided for common sizes: Icon.SIZE_STANDARD, Icon.SIZE_LARGE.
    • All Blueprint components now render Icon components instead of CSS classes (#20365)
    • See @blueprintjs/icons section below for more information
  • MenuItem
    • 🔥 Removed submenuViewportMargins and useSmartPositioning prop (#2053)
      • their functionality is enabled by default
    • 🔥 Removed rarely-used submenu prop (#2087)
      • now the only way to create a submenu is to nest <MenuItem> children
    • ⭐ smart submenu positioning is now handled by Popover and it is much better (#2053)
    • support for all HTML <a> props (#2087)
    • add multiline prop to disable ellipsis truncation (#2077)
    • text prop now accepts React.ReactNode (any single React renderable) instead of string (#2088)
    • 🎨 CSS refactor to use flex box (#2075)
      • this fixes many layout problems; most notably the text will never cover the label!
  • Popover
    • The component formerly known as Popover2 is now the default Popover (#1891)
    • Tether has been replaced with Popper.js which provides much better auto-positioning capabilities and solves a number of outstanding positioning bugs out-of-the-box.
    • ⚠️ All the classic Popover features are still supported with the same names except...
      • isModal ⇒ hasBackdrop to match corresponding prop on Overlay
      • isDisabled ⇒ disabled for consistency with HTML elements
      • tetherOptions: ITetherOptions has been replaced with modifiers: PopperJS.Modifiers
    • Add targetElementTag prop a la rootElementTag (#2276)
  • TagInput
    • 🔥 Moved component into core from labs package (#1881)
    • Added inputRef prop for consistency with InputGroup (#2034)
    • Added addOnBlur prop to invoked onAdd when input is blurred (in addition to enter key) (#1966)
    • 🎨 TagInput CSS refactor to use flex box (#2086)
      • Custom CSS will likely be required for anything other than a button or spinner in rightElement
  • Toaster
    • 🔥 single toaster.show(props, key?) method replaces toaster.update(key, props) (#1962)
    • children are rendered after state toasts for controlled usage (#2048)
  • Toast
    • message now accepts JSX
    • children can be used instead of message (and accepts JSX)
    • 🎨 CSS refactor to use better flex box (#2069)
  • 🔥 Prop rename: inline=X → usePortal=!X (#2045)
    • affects Dialog, Overlay, Popover, Tooltip, Toaster
    • note that the semantics of this prop have been reversed: inline={true} is now usePortal={false}, and vice-versa
    • the purpose of this rename is to make its meaning obvious, and to de-conflict with CSS's inline term meaning "on the same line"
  • 🔥 Callout and Dialog title now use <h4> instead of <h5> (#2134)
    • This is non-breaking if you use the React components.
  • 🔥 NavbarGroup align prop uses new Alignment enum (#2096)
  • 🔥 .pt-table is now .pt-html-table (see note in table package below) (#1906)
    • 🛠 This refactor is handled by the upgrade script.
    • its modifiers are also scoped: .pt-html-table-striped and .pt-html-table-bordered
    • Classes constants have also changed: Classes.HTML_TABLE, etc.
  • ⚠️ Tabs2 components have become the default Tabs (#1900)
  • Alert added canEscapeKeyCancel, canOutsideClickCancel, onClose, transitionDuration props (#2102)
  • KeyCombo added minimal prop to render icon and text only (#2256)
  • Label renders a <label> instead of a <div> (#1972)
  • HotkeysTarget and ContextMenuTarget decorators no longer mutate existing classes but rather act as higher-order components (#1914)
  • Overlay improved support for nested Overlays (#2033)
  • NumericInput supports continuous value change by holding down the button (#2174)
  • Tag added interactive modifier support (through .pt-interactive class) (#2251)
  • Tree nodes now support generic nodeData property for attaching arbitrary data (#2132)
    • Tree.ofType<T>() static method can be used to create a non-generic Tree component for a given nodeData type
  • 🎨 Breadcrumbs CSS refactor to remove float and use flex box (#2065)
  • Hide .pt-skeleton nested content such as items (#2284)

@blueprintjs/datetime

  • 🌟 TimePicker new useAmPm prop adds support for 12-hour format (#2151)
  • 🌟 Remove moment dependency! But...
  • 🔥 DateInput and DateRangeInput new required formatDate and parseDate callback props (#2117)
    • 🔥 format prop is now just an optional string that is passed to callbacks above
    • 🔥 placeholder prop is now on the component itself (formerly format.placeholder)
  • ⚠️ DateInput removed support for deprecated openOnFocus and popoverPosition props (#1917 #2073)
  • DateRangePicker shows new shortcuts "Yesterday" and "Today" when allowSingleDayRange is enabled (#2025)
  • 🎨 Upgrade react-day-picker dependency to 7.x (#2055)
  • 🎨 Remove TimePicker outside padding (#2271)
  • DateInput popover closes after tabbing out of the popover (#2093)

@blueprintjs/icons

  • 📦 New package for icon resources and CSS.
  • 🔥 Make sure to import @blueprintjs/icons/lib/css/blueprint-icons.css to retain icons support during the upgrade.
  • 🔥 IconClasses has been replaced with IconNames (and now lives in this new package) (#2097) 
    - className={IconClasses.AIRPLANE}
+ className={Classes.iconClass(IconNames.AIRPLANE)}
  • 🔥 support for "long" icon names pt-icon-<name> has been removed from IconName union type; only the short <name> syntax is supported (#2072) 
    - iconName={IconClasses.GLOBE}
+ icon={IconNames.GLOBE}
  • This package exports the following symbols:
    • IconContents map of NAME to unicode character
    • IconName string literal union type of all known icon names
    • IconNames map of NAME to IconName string literal
    • IconSvgPaths16 and IconSvgPaths20 for SVG icons (used by core's Icon component)
  • Renamed some keys in resources/icons.json (#2084)
    • see PR for details if you use this file

@blueprintjs/labs

  • 📦 This package no longer contains any components of its own as they've all moved to core, select, or timezone.
  • ⚠️ This package still re-exports former labs components until its next minor version release (to ease migration).

@blueprintjs/table

  • 🔥 This package no longer imports es6-shim automatically, so you may polyfill the necessary ES features however you wish (see the Usage section on the documentation home page for more details).
  • 🔥 .bp- prefix changed to .pt- for consistency with other packages (#1906)
  • 🔥 Various prop renames for consistency and clarity (#1890)
  • ⚠️ Removed deprecated props (#2073)
    • ColumnHeaderCell enableColumnInteractionBar
    • HeaderCell menu
    • ColumnHeaderCell enableColumnInteractionBar: deprecated since blueprintjs/table v1.27.0; pass this prop to Table instead.
    • HeaderCell menu: deprecated since v1.17.0; use menuRenderer instead.
  • ⚠️ Removed deprecated top-level utility functions. These should be imported from @blueprintjs/core instead (#2073)
    • arraysEqual
    • deepCompareKeys
    • getDeepUnequalKeyValues
    • getShallowUnequalKeyValues
    • shallowCompareKeys
  • ⚠️ Removed obsolete (unused but exported) RoundSize component (#1997)

@blueprintjs/select

  • New package for Select, MultiSelect, QueryList, and Omnibar (formerly Omnibox) components from labs
  • 🔥 Omnibox renamed to Omnibar (#1882)
  • 🔥 Major refactor to itemRenderer syntax: (item: T, itemProps: IItemRendererProps) => JSX.Element | null (#1877)
    • prop definition moved to QueryList so all select components support it in the same way
    • two arguments instead of one allowed for removal of generic argument on itemProps
    • itemRenderer receives modifiers object which contains active, disabled, matchesPredicate flags (with more to come in the future)
  • 🌟 Add itemListRenderer prop to all select components (#2252)
    • Pull initialContent, noResults, itemListRenderer up to QueryList props (other components extend this shared interface)
    • QueryList renderer receives rendered itemList ReactNode.
    • itemListRenderer is now the only one with access to items/itemsParentRef/renderItem props.
    • The default itemListRenderer produces a Menu using filteredItems (to preserve arrow keys order).
    • New utility function renderFilteredItems() exported from package.
  • Added type aliases for ItemRenderer<T>, ItemPredicate<T> and ItemListPredicate<T> (#2090)
  • Add filteredItems to renderer props (#2213)
  • Add query to itemRenderer props (#2245)
  • Fix so many small issues: #2135, #2212, #2216, #2209

@blueprintjs/timezone

  • New package for timezone-related datetime components.
    • Currently contains only TimezonePicker (which used to live in labs)
  • 🔥 TimezonePicker now only supports controlled usage (#2127)
    • 🔥 remove defaultValue prop
    • 🔥 value and onChange are required
    • Uncontrolled support was not fully implemented and was not widely used (not even in example)
  • Remove fuzzaldrin-plus dependency for filtering (#2127)

@blueprintjs/docs-theme

  • Renamed from @blueprintjs/docs to more accurately reflect the package contents.
  • Known code entities in prop documentation automatically become links to view that interface in a new API browser dialog (#2041)

Migration path

  • Use the provided migration script to refactor Sass, JS, and TS code automatically to address some of the API breaks.

    # After installing the latest v1.x version of Blueprint,
# the following script will now appear in your `npm bin` directory.
# run it with --help for full usage instructions.
./node_modules/.bin/upgrade-blueprint-2.0.0-rename --help

  • Import the @blueprintjs/icons CSS file alongside blueprint.css

    - <link href="path/to/node_modules/@blueprintjs/core/lib/css/blueprint.css" rel="stylesheet" />
+ <link href="path/to/node_modules/@blueprintjs/icons/lib/css/blueprint-icons.css" rel="stylesheet" />

  • Update other import paths, like the variables file.

    - @import "~@blueprintjs/core/dist/variables";
+ @import "~@blueprintjs/core/lib/scss/variables";
  (use lib/less/ in Less-based apps)

  • If you are using labs components:

    • First upgrade to @blueprintjs/labs@~0.15.3, which re-exports all the components which have been moved to other packages.
    • Then refactor your @blueprintjs/labs imports statements to import from @blueprintjs/core or @blueprintjs/select accordingly.

  • If you publish a library that depends on Blueprint:

    • You are recommended to upgrade your minimum dependencies to React 16 and Blueprint 2 and release a major version of your library.

General

v6.0 migration guides

v5.0 migration guides

Development

Contributing

Tooling

Release

Archived pages

Clone this wiki locally