Paste Manual Installation
Instructions to manually add Paste to a project.
To start using Paste, you must first install the following third party dependencies:
| Package | Version |
|---|---|
| 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.
| Package | Version |
|---|---|
| @twilio-paste/core | 20.10.0 |
| @twilio-paste/icons | 12.3.0 |
# yarn
yarn add @twilio-paste/core @twilio-paste/icons
# npm
npm install @twilio-paste/core @twilio-paste/icons
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>
);
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.
| Theme | When to use |
|---|---|
| Default | If you are not building an application for Twilio, use this theme |
| Dark | If you are not building an application for Twilio and want a dark mode, use this theme |
| Twilio | If you are building an application for Twilio, use this theme |
| Twilio Dark | If you are building an application for Twilio and want a dark mode, use this theme |
| Evergreen | If you are building an application for Segment, use this theme |
Fonts for our out of the box themes are available via the Twilio CDN and published from an internal git repository.
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.2/fonts.css" />
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 />.
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.
// 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.