Skip to content
Paste
UX Platform
Change the site theme
information:

Paste Manual Installation

Instructions to manually add Paste to a project.


Dependencies#

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

PackageVersion
react^17.0.2
react-dom^17.0.2
prop-types^15.7.2

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

# yarn
yarn add react react-dom prop-types
# npm
npm install react react-dom prop-types

Paste Packages#

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/core10.18.0
@twilio-paste/icons5.9.0
# yarn
yarn add @twilio-paste/core @twilio-paste/icons
# npm
npm install @twilio-paste/core @twilio-paste/icons

Setting up the Theme Provider#

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. We recommend the default 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>
);

How to Load the Right Font#

Default theme#

Fonts for the default theme are available via the Twilio CDN and published from an internal git repositorylink 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/main-1.2.0/fonts.css">
Information icon

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

Other themes#

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

The Whitney font is loaded by the Typography.com service and is only allowed on *.twilio.com domains as well as localhost. Make sure to serve your app from the correct hostname if you're having issues with font loading.

If you are not working in an existing Twilio Console experience, you can include the following link element in your sites head to load these fonts if you are serving your application from *.twilio.com domains.

<link rel="stylesheet" type="text/css" href="//cloud.typography.com/6230892/752864/css/fonts.css">

Tips for Testing#

Disable Animation#

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>

Handling Icons in Jest#

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 documentationlink takes you to an external page.

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

Global Styles#

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.

Black lives matter.