Skip to contentSkip to navigationSkip to topbar
Figma
Star

Paste Manual Installation

Instructions to manually add Paste to a project.


Dependencies

Dependencies page anchor

To start using Paste, you must first install the following third party dependencies:

PackageVersion
react^16.8.6 || ^17.0.2 || ^18.0.0
react-dom^16.8.6 || ^17.0.2 || ^18.0.0
@types/react^16.8.6 || ^17.0.2 || ^18.0.27
@types/react-dom^16.8.6 || ^17.0.2 || ^18.0.10

Install them in your project folder using either of these terminal commands:

# yarn
yarn add react react-dom

# npm
npm install react react-dom

Paste is split into two main packages: @twilio-paste/core and @twilio-paste/icons. Everything provided by Paste is included into those two packages.

A key distinction with Paste Core is that we include - not bundle - all of Paste; this means we expose sub-packages you can individually import. This keeps your app lean by only including the code you use. For more information, read our Paste Core documentation.

PackageVersion
@twilio-paste/core20.6.0
@twilio-paste/icons12.2.1
# yarn
yarn add @twilio-paste/core @twilio-paste/icons

# npm
npm install @twilio-paste/core @twilio-paste/icons

Setting up the Theme Provider

Setting up the Theme Provider page anchor

For Paste components to be styled correctly, you must provide them with a theme. To do so you must wrap the root of your app with the theme provider and select a theme.

import {Theme} from '@twilio-paste/core/theme';

// Wrap your root component with the Theme.Provider like so:
const App = () => (
  <Theme.Provider theme="default">
    <RestOfYourAppInHere />
  </Theme.Provider>
);

Choosing a theme

Choosing a theme page anchor

Paste includes a number of themes out of the box. Choosing the right one for your project will depend on who you are and what you are building.

ThemeWhen to use
DefaultIf you are not building an application for Twilio, use this theme
DarkIf you are not building an application for Twilio and want a dark mode, use this theme
TwilioIf you are building an application for Twilio, use this theme
Twilio DarkIf you are building an application for Twilio and want a dark mode, use this theme
EvergreenIf you are building an application for Segment, use this theme

How to Load the Right Font

How to Load the Right Font page anchor

Fonts for our out of the box themes are available via the Twilio CDN and published from an internal git repository(link takes you to an external page).

The best and most performant way to load the fonts is to include the following snippet in the <head /> of your web page.

<link rel="preconnect" href="https://assets.twilio.com" crossorigin />
<link rel="stylesheet" href="https://assets.twilio.com/public_assets/paste-fonts/1.5.1/fonts.css" />
(information)

We recommend loading the fonts directly from the Twilio CDN. This provides the fastest download time, therefore giving you the most optimized page load experience.

Alternatively, Paste will automatically load the fonts via JavaScript, so long as you wrap your application with the Theme.Provider and select the default theme. Note: this will result in slower download times than including the fonts in the <head />.

(warning)

A special note on Twilio Sans

Only Twilio applications are licensed to use Twilio Sans. If you are not building an application for Twilio, please use the default and dark themes which use an open source font called Inter.

If you are using any other theme, Paste leaves it up to you to load the fonts needed. For example, SendGrid uses Colfax. More often than not with those themes, you are working within existing applications and these fonts are automatically loaded for you.

Just like rendering Paste components in a web application, when rendering components for the purposes of testing you are required to wrap them in the Theme Provider. If you do not, your components may fail to render correctly.

It can sometimes be helpful to test Paste components without animation. To disable animations on Paste components, pass the disableAnimations boolean prop to the <Theme.Provider>.

<Theme.Provider theme="default" disableAnimations>
  {/* your content */}
</Theme.Provider>

Jest will often complain about using the esModules versions (/esm/) of Paste Icons, since it perfers the commonJS version. You'll often see an error similar to:

Test suite failed to run
  unknown: Unexpected token (1:660)
    This usually means that you are trying to import a file which
    Jest cannot parse, e.g. it's not plain JavaScript.
    ...

In order to fix these Jest errors, you'll need to configure Jest to correctly handle the esModules versions of Paste Icons.

You can use the transformIgnorePatterns option to tell Jest to not transform Paste Icons, which allows Jest to transpile these files. More information about transformIgnorePatterns can be found by reading the Jest documentation(link takes you to an external page).

// jest.config.js
{
  "transformIgnorePatterns": [
    "/node_modules/@twilio-paste/icons/.*"
  ]
}

Many apps/websites utilize global stylesheets. Even though Paste styles are scoped at the component level, global styles can creep in and cause some havoc. Make sure to thoroughly test Paste components to verify everything looks as they should.