Skip to contentSkip to navigationSkip to topbar
Figma
Star

Upgrade Guide

Summary of Breaking Changes to Core, with actions that should be taken before upgrading


Core 20.0.0 - August 2023

Core 20.0.0 - August 2023 page anchor

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

Core 19.0.0 - March 2023

Core 19.0.0 - March 2023 page anchor
  • 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(link takes you to an external page).

See the full change list.

Core 18.0.0 - February 2023

Core 18.0.0 - February 2023 page anchor

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.

Core 17.0.0 - October 2022

Core 17.0.0 - October 2022 page anchor
  • [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.

Core 16.0.0 - October 2022

Core 16.0.0 - October 2022 page anchor
  • [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(link takes you to an external page)

    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(link takes you to an external page).

Core 15.0.0 - August 2022

Core 15.0.0 - August 2022 page anchor
  • [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(link takes you to an external page).

  • [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(link takes you to an external page).

  • [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(link takes you to an external page).

  • [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(link takes you to an external page).

  • [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.

    // 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(link takes you to an external page).

  • [Truncate] title prop is required for the Truncate component. More details: fa2ffc5c(link takes you to an external page) #1603(link takes you to an external page)

    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.

    // 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(link takes you to an external page).

  • [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(link takes you to an external page) #1307(link takes you to an external page)

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

    Twilio
    // prior to upgrade:
    <Button as="a" href="https://twilio.com">Twilio</Button>
    
    // 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(link takes you to an external page) #1307(link takes you to an external page)

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

    // 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(link takes you to an external page).

  • [Disclosure] style prop is now being blocked by safelySpreadBoxProps, so any additional styles will no longer be rendered. More details: b8265071(link takes you to an external page)

    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>
Component preview theme
// AFTER action taken:
<Disclosure>
<DisclosureHeading as="h2" variant="heading40">
Disclosure Heading
</DisclosureHeading>
<DisclosureContent>
Content
</DisclosureContent>
</Disclosure>

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} />

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>

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'