🎉 This is the biggest major release so far 🎉

High Level Improvements

• Brand new documentation experience available on evergreen.segment.com
• React upgraded to v16.3.
• New Icon component using BlueprintJS icons
  • All legacy icons deprecated.
• Intent API added to Button, IconButton, Alert, InlineAlert, Dialog, CornerDialog, Table.Row and Menu.Item.
  • intent property that accepts: none, success, danger, warning
  • appearance property changed to accept: default, minimal, primary
• Pane APIs changed.
  • appearance is deprecated for background.
• Improvements to z-index management with the new Stack component.
• Improvement and additions to the Table component
  • Components are exported from Table directly. Table.TextCell, Table.Row etc.
  • Height is now managed by the Table.Row and default is 48
  • New Table.EditableCell component.
  • New Table.SelectMenuCell component.
  • New Table.VirtualBody component.
• minorScale and majorScale exported.
• New Menu component
• Theming support with React.createContext.
  • New color system.
  • Updated typography system.
  • Themer object for help with generating styles.

Deprecated Components and Styles

• Theme related
  • colors
  • TextStyles,
  • FontFamilies,
  • TextColors,
  • ButtonAppearances
  • BadgeAppearances
  • LinkAppearances
  • TextInputAppearances
  • CheckboxAppearances,
  • controlBaseStyle,
  • FillAppearances,
  • InputAppearances,
  • selectableRowStyle,
  • selectableTabStyle,
  • getBorderRadiusForControlHeight,
  • getBorderRadiusForTextSize,
  • getIconSizeForControlHeight,
  • getTextSizeForControlHeight,
  • getTextStyleForControlHeight
  • SegmentedControlAppearances
  • SelectAppearances
  • ElevationStyles,
  • BorderColors,
  • LayerAppearances
• icon related
  • IconAim
  • IconColors
  • IconMap
  • AddIcon
  • ArrowIcon
  • CheckCircleIcon
  • CogIcon
  • DangerIcon
  • QuestionIcon
  • SearchIcon
  • TriangleIcon
  • WarningIcon
  • Icon (is now a completely different component with the same name)

Components with Breaking Changes

• Button
  • IconButton
  • BackButton
• Pane
• Card
• Avatar
• Badge
• Pill
• Dialog
• Alert
• SelectMenu
• Typography
  • Link
  • Heading
  • Text
• Table
  • TableBody
  • TableCell
  • TableHead
  • TableHeaderCell
  • TableRow
  • TextTableCell
  • TextTableHeaderCell
  • SearchTableHeaderCell

Upgrade Guide

Theme

One of the biggest changes in Evergreen v4 is the addition of a theming layer. The goal of this theming layer in this version is not to offer a simple theming mechanism, but rather create a flexible foundational API we can simplify in the future. Although Evergreen exposes theming capabilities. It's still considered a private API. Breaking changes may occur in minor releases.

Theme Utilities

The theming API uses the React.createContext API added in React v16.3.0. Evergreen exports the following utilities for theming:

• ThemeProvider
• ThemeConsumer
• withTheme
• defaultTheme

ThemeProvider

The ThemeProvider is used to provide a new theme to all child ThemeConsumers. Please refer to the code to learn how this works.

ThemeConsumer

The ThemeConsumer is the best way to access the current theme object. This is primarily useful for documentation. To create components that rely on the theme object, the withTheme HoC is the preferred method to access the theme object.

 <ThemeConsumer>
    {theme => (
      ...
    )}
</ThemeConsumer>

withTheme

To create components that rely on the theme object, use the withTheme HoC. You will see the following pattern being used within Evergreen:

import React from 'react'
import PropTypes from 'prop-types'
import { withTheme } from 'evergreen-ui' // Within Evergreen this is relative.

class Alert extends React.Component {
  static propTypes = {
    /**
     * Theme provided by ThemeProvider.
     */
    theme: PropTypes.object.isRequired
  }
  
  // Component definition...
}

// Export the component with the withTheme HoC
export default withTheme(Alert)

defaultTheme

The recommended way to access the theme should be through the ThemeConsumer. However, the default theme is also directly exported to help with migration from v3 to v4. The main use case is to migrate places in which you import colors and TextStyles directly.

Colors

The color system in Evergreen is located in the theme and is used throughout the theme. There is no real dependency on any of the colors directly within components. Components always access a theme color or property through a get function. For example, theme.getTextColor is a required function in the Evergreen theme, theme.colors is not a required property and not directly used.

Colors are no longer directly exported from Evergreen. They are available on the defaultTheme or through a ThemeConsumer preferably.

To help with the upgrade process, some useful variables are available on the defaultTheme:

import { defaultTheme } from 'evergreen-ui'

• defaultTheme.colors — functional theme colors.
• defaultTheme.palette — palette colors. Each color group has 4 variations: lightest, light, base, dark.
• defaultTheme.scales — blue and neutral have a more advanced scale of 10 colors.
• defaultTheme.fills — colors used for Avatars, Badges, Pills.

Palette

Mapping old colors

• turquoise is renamed to teal.
• pink colors is deprecated.
• orange color is added
• v4 no longer uses yellow for the warning intent. Please use the orange warning color instead.

Mapping base 500 colors to the defaultTheme.palette

The easiest colors to map to the new colors are base colors. Which previously were labeled as 500.

Mapping dark 1000 colors to the defaultTheme.palette

You can map any color that is 900 or 1000 to the dark variant.

Mapping light 30 colors to the defaultTheme.palette

You can colors that are around 30 to the light variant.
If you need different colors for different states use a lighten/darken function.

Mapping lightest 5 colors to the defaultTheme.palette

You can map colors that are around 5 to the lightest variant.
If you need different colors for different states use a lighten/darken function.

Exact Mapping 3A–400A colors with tinycolor2

Exact Mapping 3–400 colors with tinycolor2

Almost Exact Mapping 600–1000 colors with tinycolor2

There is currently no longer any colors for 600, 700, 800, 900 colors for palette colors.
We do export a new defaultTheme.scales property that exports some extra shades for blue and neutral. However, if you need a almost exact match to the old colors use tinycolor2.

Mapping Icon example

Pane + Card

Appearance is now background.

• The Pane component no longer accepts the appearance property. Use the background property instead.
  • appearance="selected" is deprecated.
  • appearance="dark" is deprecated.
  • appearance="tint3" is deprecated. Use background="tint2" instead.

Borders are different. extraMuted is deprecated.

• Borders don't support the extraMuted property anymore. Use muted instead.
• BorderColors.muted in v3 is default in v4
• BorderColors.extraMuted in v3 is muted in v4
• BorderColors.default is deprecated

Button

• [Breaking] intent property that accepts: none, success, danger, warning
• [Breaking] appearance property changed to accept: default, minimal, primary
• [Breaking] Icons now use BlueprintJS icons.
• [Change] Minimal default button now has a blue text color
• [Fix] Bring back cursor: not-allowed; when buttons are disabled
• [Fix] Fixed marginTop on the Button component. #240

Before / After

IconButton

• [Breaking] intent property that accepts: none, success, danger, warning
• [Breaking] appearance property changed to accept: default, minimal, primary
• [Breaking] Icons now use BlueprintJS icons.
• [Add] Add iconSize prop to IconButton component. #317

Icon

• Icons now use BlueprintJS icons
• Icons are no longer wrapped in a Box.
• Icons now accept the size property.
• aim prop deprecated
• iconWidth prop deprecated
• iconHeight prop deprecated

Icons with aim

v4 no longer supports the aim property on icons. Instead use the icon for it.

Avatar

• Avatar appearance is deprecated. Use color prop instead.

Badge + Pills

• Badge + Pill appearance is deprecated. Use color prop instead.

Dialog

• Dialog now implements the intent API.
• type prop deprecated. Use intent instead.

Alert

• Alert now implements the intent API.
• type prop deprecated. Use intent instead.
• Properly align icon #214
• Use Heading and Paragraph instead of Text

Typography

All typography information is now passed through the theme.
The following documentation describes the default theme settings.

• The SubHeading component is deprecated.
• Typography components now export the ability to set a default margin top: marginTop="default"

Typography - Text

• Text styles are passed through the theme
• Text only support size={300 | 400 | 500 | 600}.
  • Default size is now 400
  • 600 is only there for the Link component that can be used as a big breadcrumb in some cases and is based on the Text component

Deprecated

• color="extraMuted" is deprecated. Use color="muted" instead.
• isUppercase prop is deprecated.
• textStyles prop is deprecated.
• textUppercaseStyles prop is deprecated.

Typography - Paragraph

• Paragraph no longer implements the Text component...

• ...instead paragraph styles are passed through the theme independently.

• Paragraph only supports size={300 | 400 | 500}. Not 600!

  • Default size is now 400

• inherited props from Text are deprecated

  • isUppercase prop is deprecated.
  • textStyles prop is deprecated.
  • textUppercaseStyles prop is deprecated.

Typography - Heading

• Heading no longer implements the Text component...

• ...instead heading styles are passed through the theme independently.

• Font family display is used for text sizes above and including 20px.

• Font family ui is used for text sizes below 20px

• Heading sizes support size={100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900}.

  • size={100} is uppercase
  • Colors are explicitly set in the theme.

• isUppercase prop is deprecated.

• inherited props from Text are deprecated

  • textStyles prop is deprecated.
  • textUppercaseStyles prop is deprecated.

Typography - Link

• appearance deprecated for color.
• Default color is blue instead of green.
• Link accepts size={300 | 400 | 500 | 600}.

Table

• Components are exported from Table directly. Table.TextCell, Table.Row etc.
• No longer a default borderRight on table cells.
• Height is now managed by the Table.Row and default is 48.
• intent prop added to Table.Row.

Table.Cell

• [Add] Add rightView property, mainly for icons + icon buttons. #278

Table.Row

• [Improvement] Support string value such as height="auto" for Table.Row height
• [Improvement] Table.Row uses keyboard navigation (ArrowUp/Down) instead of tabbed navigation. #274
• [Fix] Fixed mainRef #303 .

Table.VirtualBody (new)

• [New] Table.VirtualBody component. #267
• [Fix] Force children to be an array
• [Fix] Gracefully support strings as children
• [Fix] Expose overscanAmount property
• [Fix] Improve scrolling. Use a array of heights for itemSize when allowAutoHeights is false.
• [Fix] Fix height calculation of the VirtualBody in some edge cases. #288.

Table.SelectMenuCell (new)

• [New] Table.SelectMenuCell — editable table cell component. #274
• [Add] default caret-down icon for the rightView property. #278
• [Fix] Table.EditableCell accepts textProps properly. #280
• [Improvement] Added disabled property. #280
• [Improvement] Added placeholder property. #280
• [Improvement] Added isSelectable property. #280
• [Fix] isSelectable default prop is now true. #283
• [Fix] Filter out size property. #282
• [Improvement] Table.SelectMenuCell now toggles the SelectMenu on single click when focused. #291
• [Improvement] Table.SelectMenuCell now has cursor: pointer; when selected. #291

Table.EditableCell (new)

• [New] Table.EditableCell — table cell that implements a SelectMenu. #274
• [Add] disabled property. #278
• [Add] placeholder property. #278
• [Improvement] Make isSelectable prop optional. #278
• [Fix] Table.EditableCell accepts textProps properly. #279
• [Fix] Filter out size property. #282
• [Fix] Table.EditableCell position should be relative to viewport. #285
• [Fix] Hitting "ESC" on EditableCell cancels the edit. #290

Button

• [Bugfix] Fix missing focusAndActive state in getButtonClassName #269

Scales minorScale and majorScale

Evergreen now exports two helper methods to conform to the 4 (px) minor scale and 8 (px) major scale.

import { minorScale, majorScale } from 'evergreen-ui'

minorScale(1) // => 1*4 = 4
minorScale(3) // => 3*4 = 12

majorScale(1) // => 1*8 = 8
majorScale(2) // => 2*8 = 16
majorScale(3) // => 3*8 = 24
majorScale(4) // => 4*8 = 32

Both scales only except integers as input and will otherwise throw a TypeError.

Stack component and Stacking

V4 ships a fix for nesting Popovers, SelectMenu and Combobox in Dialogs and SideSheets. And layering Dialogs on top of Dialogs. Essentially allowing infinite layering anything that uses a Stack component.

Changes

• Use React 16.3.0
• Use createContext API
• Export StackingContext from evergreen-ui
• Export Stack component from evergreen-ui
• Export StackingOrder object with z-index presets from evergreen-ui.
• Remove zIndex props from Popover, Combobox and Positioner.

StackingContext

The StackingContext is a React context with a default value (z-index) of 10. The StackingContext is currently only used within the Stack component within Evergreen.

Stack component

The Stack component uses the StackingContext which accepts a function as children. That function takes in the zIndex and should return a React node:

static propTypes = {
  /**
   * Function that takes the current z-index and returns a React Node.
   * (zIndex) => ReactNode.
   */
  children: PropTypes.func.isRequired,

  /**
   * Set the value of the stack. This will increment for children.
   */
  value: PropTypes.number
}

Inside of the render function the Stack component first looks for the current value. Passing a value to the component will make sure the highest of the two are used. This is useful because Overlays start at a z-index of 20. See more info below about StackingOrder. The Stack component will pass the current value to the current children, and increment the value for the next consumer.

render() {
  const { children, value } = this.props
  return (
    <StackingContext.Consumer>
      {previousValue => {
        const currentValue = Math.max(value, previousValue)
        const nextValue = currentValue + 1
        return (
          <StackingContext.Provider value={nextValue}>
            {children(currentValue)}
          </StackingContext.Provider>
        )
      }}
    </StackingContext.Consumer>
  )
}

Stack component usage

In most cases Stack will be an internal component, we are exposing it if you want to build custom components on top of this logic.

<Stack value={StackingOrder.POSITIONER}>
  {zIndex => {
    return (
      /* ... code omitted */
    )
  }}
</Stack>

StackingOrder

The values here are somewhat random, the reason why POSITIONER and OVERLAY are 10 apart is that in between the Stack component can increment the z-index — giving a head room of 10 z-indexes.

/**
 * Stacking order contains z-index values that are used through.
 * Note that the Stack component might increase the z-index for certain components.
 */
export default {
  /**
   * Used for focused buttons and controls.
   */
  FOCUSED: 2,

  /**
   * Used as the default for the StackingContext.
   */
  STACKING_CONTEXT: 5,

  /**
   * Used as the default for the Positioner.
   */
  POSITIONER: 10,

  /**
   * Used for the Overlay and everything that's inside such as Dialog + SideSheet.
   */
  OVERLAY: 20,

  /**
   * Used for the toasts in the toaster. Appears on top of everything else.
   */
  TOASTER: 30
}

StackingOrder Example

I tweeted about this with a video attached. Click the link below to see.

React.createContext is a great solution for solving automatic stacking order when using portals for modal dialogs, popovers, panels and sheets. #reactjs pic.twitter.com/9RImVl2ISV

— Jeroen Ransijn 🌲 (@Jeroen_Ransijn) April 17, 2018

Toaster

• [Breaking] toaster.info is deprecated. Use toaster.notify instead.
• [Bug fix / edge case] Fix toaster conflict with multiple version of Evergreen. #332

SelectMenu

• [Improvement] isMultiSelect prop added to SelectMenu. Use when using multi select.
• [Fix] SelectMenu selection now skips filtered items. Only visible items are selected.
• [Fix] SelectMenu scrolls to the selected item by setting scrollToIndex on VirtualList.
• [Fix] Fix SelectMenu search when 0 results. #302

Tooltip

• [Fix] Fixed tooltip by exporting getTooltipProps from theme (bug)
• [Fix] Fixed hiding Tooltip when isShown={false} #265

Select

• [Fix] Use autoFocus prop instead of autofocus #213
• [Fix] Fixed prop type bug in Select string.required => string.isRequired #212
• [Fix] Fixed a style issue with <Select /> when placed inside flex containers or when allowed to have an unconstrained width (width: auto) by including paddingRight={sizeOfIconPlusPaddingX}. #237

TextInputField / FormField

• [Improvement] Add hint property to TextInputField which is under the input element. FormFieldHint
• [Improvement] Description moved above the input element, instead under.
• [Fix] Fixed alignment slightly of icon in FormFieldValidationMessage

TextInputField

• [Improvement] Set default TextInputField height to 32 instead of 36 #220.

SegmentedControl

• [Improvement] add focus support to Segmented Control radios. #241
• [Improvement] boolean, number and string values now all properly supported. #281

Select / SelectField

• [Fix] Export the SelectField #238
• [Add] Add support for uncontrolled behavior by adding a defaultValue prop to Select #245

Menu (new)

• [New] Menu.Item component
• [New] Menu.Group component
• [New] Menu.Divider component
• [New] Menu.Option component
• [New] Menu.OptionsGroup component
• [Improvement] Add better focus management to the Menu component
  • Support Home and End key to jump to first and last component
  • Support custom [role="menuitem"] and [role="menuitemradio"] elements within the Menu.

UnorderedList, OrderedList, ListItem

• [Add] Add size prop to OrderedList and UnorderedList
• [Add] Add iconColor and icon prop to OrderedList and ListItem
• [Improvement] When using icon/iconColor in OrderedList and ListItem, ListItem will override the property
• [Fix] Fixed prop warnings and make list components more flexible. #315

SidebarTab

• [Improvement] Deprecate the icon in the SidebarTab component #250

Popover

• [Fix] popover not closed when button being clicked. #219
• [Improvement] Pressing down arrow on trigger brings focus inside of Popover content.
• [Improvement] Disable bringing focus inside by default, which is more inline with how a popover or menu should work
• [Improvement] Adds support for nesting Tooltip in Popover #239

Positioner

• [Fix] Fixed jitter in Positioner which affects Popover and Tooltip. #257
• [Fix] Improved Positioner calculations and transform-origin. #259
• [Improvement] Add support for Position.LEFT and Position.RIGHT. #299
• [Fix] Remove empty divs from Positioner Portal. #330
• [Improvement] slightly improve positioning (by rounding instead of ceiling)

Position

Position constant values updated throughout Evergreen.

Position.TOP // 'top',
Position.TOP_LEFT // 'top-left',
Position.TOP_RIGHT // 'top-right',
Position.BOTTOM // 'bottom',
Position.BOTTOM_LEFT // 'bottom-left',
Position.BOTTOM_RIGHT // 'bottom-right',
Position.LEFT // 'left',
Position.RIGHT // 'right'

SideSheet

• [Improvement] Add left, right, top, bottom positions to SideSheet: #252

Dialog

• [Fix] Call onCancel when cancel button is triggered #266
• [Improvement] The Dialog component now resizes gracefully to fit the available viewport. A sideOffset property was also added which controls the space on the left/right sides of the Dialog when there isn't enough horizontal space available on screen. #301
• [Improvement] Add horizontal scrolling support. #314

Dialog + Overlay + SideSheet

• [Improvement] shouldCloseOnEscapePress and shouldCloseOnClick to Overlay, Dialog, and SideSheet #324
• [Bug fix] Fixes a bug where Dialog's did not trigger the onCancel handler when the close button was clicked. #324

Checkbox

• [Improvement] Add indeterminate state to Checkbox component. #313
• [Bug fix] Fix jumping behavior in scrollable lists and tables. #318

Radio

• [Breaking] bubble event in radio onChange #341
• [Fix] Fixed jumping behavior in scrollable lists and tables. #318
• [Fix] Fixed a bug where indeterminate radios (one or more radios that are not checked) looked like they were selected. #340

Other Changes

• Upgrade most of the dependencies #344
• Add displayName's to all the components.
• Add a displayName to withTheme

Docs

• Docs is completely redesigned.
• Docs is now using Gatsby v2.