Upgrade Guide

Updated the compilation target of our JavaScript bundles to be browser and not node. This has resulted in a small 24.5 kB reduction in file size across the entire Core library.

ACTION NEEDED: None. This should be 100% backwards compatible, but you should be aware you are running different code.

See the full change list

• We have moved @types/react and @types/react-dom to peer dependencies of the library. This should allow for greater control and backwards compatibility with older versions of React as Paste is no longer bundling the type libraries. Your application likely has both of these as dependencies anyway, but it is now up to you to manage that version number.

Action needed

Ensure @types/react and @types/react-dom are installed as dependencies of your application.

• Removes the __console_patch prop from the Toast package. This was a temporary z-index fix for Twilio Console that is no longer necessary.

ACTION NEEDED: No action should be necessary. If you are still using the __console_patch prop with Toast and this change affects your codebase, please reach out to us with a Github Discussion.

See the full change list.

• Adds support for React 18. This should "just work" and remains backwards compatible. Let us know if you have any issues.
• This major version included listing all the missing peer dependencies for each Paste package.
• Deprecated light/dark named design tokens have been removed.

ACTION NEEDED: If you are using a package from Paste in isolation (not from @twilio-paste/core), be sure to correctly install all the missing peer dependencies.

ACTION NEEDED: If you are using the deprecated light/dark named design tokens, you will need to update your references to the new weak/strong named design tokens. You can find the new design tokens in the design tokens changelog.

See the full change list.

• [Switch] Updated Switch component API to match other form components in Paste.

  • SwitchContainer has been replaced with SwitchGroup
  • SwitchGroup props changes:
    • removes id?: string
    • removes label: ReactNode - use the new legend prop instead.
    • adds legend: string | NonNullable<React.ReactNode> to replace the old label prop.
    • adds errorText?: string | React.ReactNode to handle error states.
    • adds orientation?: 'vertical' | 'horizontal; to set children orientation.
    • adds i18nRequiredLabel?: string to change the required label for internationalization.
    • adds name: string to label the switch group for forms.
    • adds onChange?: (checked: boolean) => void to handle changes to any child Switch's checked state in a single function.
    • helpText prop now accepts a string.
    • required prop is now optional.
    • element prop default value changed to SWITCH_GROUP from SWITCH_CONTAINER
  • Switch props changes:
    • children prop type changed to NonNullable<React.ReactNode>
    • adds hasError?: boolean to handle error states.
    • adds helpText?: string | React.React.Node to add additional context to a switch.
    • adds checked?: boolean to use the Switch in a controlled manner.
    • adds defaultChecked?: boolean to set the default checked value in an uncontrolled manner.

ACTION NEEDED: If you are using the Switch component, you will need to update your code to use the new API. You can find the new API in the Switch documentation.

See the full change list.

• [Modal] We removed the `__console_patch`` prop because it is no longer necessary. It was a hack needed for the legacy Console application, which is no longer in use. See PR #2697

  ACTION NEEDED: None, but the __console_patch prop will no longer work if you are on a legacy application and need to use the Modal component. We recommend migrating to the new Console application.

See the full change list.

• [Design tokens] Created a new category of design token, Data Visualization, and subsequently relocated all of the Data Visualization tokens from the generic Color category. If you are using categorized Data Visualization design tokens, you will need to update their reference.

  ACTION NEEDED: If you are referencing the color.dataVisualization tokens directly from the @twilio-paste/design-tokens package, you will need to update your references to the dataVisualization bucket.

See the full change list.

• [Textarea] Update Textarea to use @twilio-paste/react-autosize-textarea library and add the resize prop which allows users to resize the Textarea height.

  ACTION NEEDED: None, but because @twilio-paste/react-autosize-textarea is a new peer dependency requirement of @twilio-paste/textarea, out of an abundance of caution with how npm and yarn differ with regards to handling peer dependencies, we decided to mark this change as a major to be safe.

See the full change list.

• [Styling Library] Upgrade to Emotion v11 from v10.

  ACTION NEEDED: None, the upgrade from v10 to v11 is largely a backwards compatible upgrade, but there were significant changes to the types exported from Emotion that could impact compilation of your application when using Typescript.

See the full change list.

• [Icons] Add React.forwardRef to all Icon components.

  ACTION NEEDED: None, but you should be aware of the change due to the fact that refs on Icons are now assigned differently, and there is the potential for exported types to be different.

See the full change list.

• [Design Tokens] Remove the Console theme from the Design Tokens package, as that design language is officially deprecated.

  ACTION NEEDED: If you were importing the Console theme directly from the Design Tokens package, you should switch your import statements to use the Default, Dark, or SendGrid themes.

  Copy code block

  // Before:
  import DefaultRawTokenJSON from '@twilio-paste/design-tokens/dist/themes/console/tokens.raw.json';
  import {
    backgroundColors
  } from '@twilio-paste/design-tokens/dist/themes/console/tokens.common';
  
  // AFTER
  import DefaultRawTokenJSON from '@twilio-paste/design-tokens/dist/tokens.raw.json';
  import {
    backgroundColors
  } from '@twilio-paste/design-tokens/dist/tokens.common';
  

See the full change list.

• [Truncate] title prop is required for the Truncate component. More details: fa2ffc5c #1603

  ACTION NEEDED: Add a title prop to all uses of the Truncate component. This prop should be a string that matches the contents of the component.

  Copy code block

  // prior to action taken:
  <Truncate>Some very long text to truncate</Truncate>
  
  // AFTER action taken:
  <Truncate title="Some very long text to truncate">Some very long text to truncate</Truncate>
  
  

See the full change list.

• [Button] Button components used as links (as="a" and href="") now automatically add an arrow icon if children is a string. This is a design breaking change that you should be aware of when upgrading. More details: 1bcb8b30 #1307

  ACTION NEEDED: Inspect all instances of Buttons as links, ensuring the design change works as intended for your layout.

  Twilio
  Copy code block

  // prior to upgrade:
  <Button as="a" href="https://twilio.com">Twilio</Button>
  

  Twilio
  Copy code block

  // AFTER upgrade:
  <Button as="a" href="https://twilio.com">Twilio</Button>
  

• [Button] Additional validation added to throw an error if the disabled or loading props are set to true for a Button as link. This is a functionality breaking change to existing disabled link buttons. More details: 1bcb8b30 #1307

  ACTION NEEDED: Ensure there are no instances of Buttons as links that use disabled or loading props as true.

  Copy code block

  // prior to action taken:
  <Button as="a" href="https://twilio.com" disabled>Twilio</Button>
  
  // AFTER action taken:
  <Button as="a" href="https://twilio.com">Twilio</Button>
  
  

See the full change list.

• [Disclosure] style prop is now being blocked by safelySpreadBoxProps, so any additional styles will no longer be rendered. More details: b8265071

  ACTION NEEDED: Ensure there are no instances of Disclosure that use the style prop.

//prior to action taken:
<Disclosure style={{background-color: 'red'}}>
 <DisclosureHeading as="h2" variant="heading20">
    Disclosure Heading
  </DisclosureHeading>
  <DisclosureContent>
    Content
  </DisclosureContent>
</Disclosure>

// AFTER action taken:
<Disclosure>
  <DisclosureHeading as="h2" variant="heading40">
    Disclosure Heading
  </DisclosureHeading>
  <DisclosureContent>
    Content
  </DisclosureContent>
</Disclosure>

• [Several Components] Many components now use fowardRef, allowing for ease in passing down refs. The full list is available below. More details: commit history

ACTION NEEDED: No action is needed, but you can now pass a ref down to a component easily, as shown in the following example.

<Alert ref={ref} />

• [Theme] The Color key has been removed from the theme. This makes for a better experience as there are no duplicate colors. Each type of color has their own key on theme. More details: commit history

• [Core] The Absolute component has been deprecated. For a replacement use the Box component with absolute positioning. More details: 84c22b4

Action Needed: Replace any Absolute components with a Box component with the position prop set to absolute.

// prior to action taken:
<Absolute>Content goes here</Absolute>

// AFTER action taken:
<Box position="absolute">Content goes here</Box>

• [Core] The Core package no longer bundles the '@twilio-paste/form' package. All components previously in '@twilio-paste/form' are now available separately within core. More details: commit history

Action Required: Update any import statements from '@twilio-paste/form' to use '@twilio-paste/core' instead.

// prior to action taken:
import {Input} from '@twilio-paste/form'

// AFTER action taken:
import {Input} from '@twilio-paste/core/input'