Blueprint 3.0

🆙 Migration guide

Before: Migrating from 1.x to 2.x

Refer to the Blueprint 2.0 migration guide and changelog to familiarize yourself with the API breaks in 2.0. You can upgrade straight from 1.x to 3.x by running both upgrade scripts. It is recommended to read both guides before beginning as the information here is more relevant (since things have changed between 2.0 and 3.x)

Before: TSLint rules

You may want to enable the blueprint-classes-constants TSLint rule to detect hardcoded string literals in JS/TS code and migrate those to use Classes constants.

3.0.0 no longer uses the pt- prefix for class names. It has been changed to bp3- to avoid conflicts when multiple Blueprint versions are on the same page. It will continue to change in future major versions. Using the Classes constants is the forward-proof solution here as those names will remain the same as namespaces change. And if those names do change, they're much easier to detect and can even be validated by the TypeScript compiler.

🛑 Resolve lint failures before upgrading Blueprint packages. It'll make the style upgrade a lot friendlier.

1. Installation

The latest 3.0.0 package can be installed using the @latest NPM tag:

yarn upgrade @blueprintjs/core@latest @blueprintjs/icons@latest ...

2. Upgrade script

Run the migration script on your source code to automatically 🔁 rename changed symbols. This will handle all the API renames below and log extensive warnings for breaks that require your intervention.

# if your codebase was on 1.x, first run the 2.0.0 upgrade script:
$(npm bin)/upgrade-blueprint-2.0.0-rename --path=path/to/src

# then run the 3.0.0 upgrade script.
$(npm bin)/upgrade-blueprint-3.0.0-rename --path=path/to/src

# pass --help for usage documentation and other options

3. Manual migrations

At this point, most of the API breaks should be addressed. Get your build passing and audit your newly upgraded app to ensure that it performs as expected. If things look out of place or don't work as expected, you may need to revisit the release notes to make sure you didn't miss any breaks.

4. SVG icons

One of the flagship features in Blueprint 2.0.0 was the introduction of SVG icons to replace the icon font. All the Blueprint React components now render exclusively SVG icons, which may affect your app styles in subtle ways. Some notes about the switch to SVG icons:

• A new package @blueprintjs/icons was introduced in 2.0.0 that provides the icon font and the SVG paths.
  • @blueprintjs/core depends on this package so it'll be installed automatically, but it's still a good idea to explicitly depend on it in your package.json as it updates independently.
  • ⚠️ Don't forget to include blueprint-icons.css in your application styles.
• The icon font is still supported but should be considered a legacy feature. The React components never use it though their styles still support it through className. You can access font icons directly through Classes.iconClass(iconName) and Classes.ICON_STANDARD/LARGE.
  • 🔥 Classes.ICON_STANDARD and Classes.ICON_LARGE are never used by the React components anymore. Sizing is handled by the iconSize prop (see last bullet below).
• 🔥 The IconClasses enum has been replaced with IconNames and icon names no longer support the "pt-icon-" prefix.
• 🔥 All React icons are now <span className={Classes.ICON}> elements and they contain SVG markup for the icon image.
  • Icons can still be colored using the color CSS property or the SVG fill property.
• 👍 Gone are the days of size classes, as SVG icons can now be rendered at any pixel size.
  • <Icon iconSize={#}> will render the icon at exactly #px and will use the closer of the 16px or 20px icon glyphs.
  • Constants are provided for common sizes: Icon.SIZE_STANDARD, Icon.SIZE_LARGE.