Skip to contentSkip to navigationSkip to topbar
Paste
Paste assistant Assistant
FigmaStar

Customization Provider

Version 8.2.0GithubStorybook

The Customization Provider provides functionality to change token values and the style of Paste components.

(warning)

This page is not for Twilio employees!

If you're a Twilio employee, check out How to build custom UI with Paste tokens and primitives to learn how and when to build custom components in a Twilio feature. You should not use CustomizationProvider inside ThemeProvider, and it likely won't give you the styles you expect. Customization Provider only accepts base themes of default and dark for Twilio customers to use.

The CustomizationProvider provides a central place for customizations to be applied to an application using Paste. If you want to build a web application or website using Paste, but want to have your own look and feel—the CustomizationProvider exists to do just that.

If you’re a Flex customer, and want to build a Flex plugin that follows your brand guidelines, the CustomizationProvider can be used for that as well.

About the Customization Provider

About the Customization Provider page anchor

Similar to the Paste ThemeProvider, the CustomizationProvider uses React Context(link takes you to an external page) to provide a theme object to any descendant components in the tree.

The CustomizationProvider currently differs in two ways:

  1. Firstly, you set a baseTheme. The base theme tells the provider which Paste theme you would like to base your custom theme on. You can choose from the 'default' or 'dark' Theme.
  2. Secondly, you set a theme, but unlike with the <Theme.Provider /> you pass it an object.

Selecting a Base Theme

Selecting a Base Theme page anchor

Selecting a base theme allows you to choose which Paste theme you would like to build on top of. By default we select the default theme for you, but if you would like to create a custom application using a dark theme, you can choose the dark baseTheme as your starting point.

import {CustomizationProvider} from '@twilio-paste/core/customization';

const MyApp = () => (
  <CustomizationProvider baseTheme="dark">
    rest of app
  </CustomizationProvider>
)

Providing a Theme Object

Providing a Theme Object page anchor

For the theme prop you can pass a complete theme object or a partial theme object for smaller customizations. If a partial theme object is passed, the CustomizationProvider merges the custom theme object with the base Paste theme you chose. For example, if you want to customize certain background color tokens of the Dark theme you would only need to pass the following:

import {CustomizationProvider} from '@twilio-paste/core/customization';

const MyApp = () => (
  <CustomizationProvider baseTheme="dark" theme={{
    "backgroundColors": {
      "colorBackgroundPrimary": "rgb(80, 123, 30)",
      "colorBackgroundPrimaryStronger": "rgb(56, 86, 21)",
      "colorBackgroundPrimaryWeaker": "rgb(154,199,232)",
      "colorBackgroundPrimaryWeakest": "rgb(197, 223, 242)",
    }
  }}>
    rest of app
  </CustomizationProvider>
)

This will output the Paste theme of your choice with the custom background color tokens above. So any component using colorBackgroundPrimary, colorBackgroundPrimaryStronger, etc will use the custom background color token values instead of the background color token values provided by the base theme.

The theme object should follow the following format, where each theme key can take any valid design token for that grouping:

Object {
  "backgroundColors": Object {},
  "borderColors": Object {},
  "borderWidths": Object {},
  "breakpoints": Object {},
  "colorSchemes": Object {},
  "dataVisualization": Object {},
  "fontSizes": Object {},
  "fontWeights": Object {},
  "fonts": Object {},
  "heights": Object {},
  "iconSizes": Object {},
  "lineHeights": Object {},
  "maxHeights": Object {},
  "maxWidths": Object {},
  "minHeights": Object {},
  "minWidths": Object {},
  "radii": Object {},
  "shadows": Object {},
  "sizes": Object {},
  "space": Object {},
  "textColors": Object {},
  "widths": Object {},
  "zIndices": Object {},
}

Custom themes can also be stored in their own files and imported as a json object. As long as the imported custom theme follows the format of the Paste theme object, you can pass it directly to the theme prop.

The CustomizationProvider should wrap the root of your application, or a part of the application you would like to theme.

import {CustomizationProvider} from '@twilio-paste/core/customization';
import CustomTheme from './themes/theme.json';

const MyApp = () => (
  <CustomizationProvider baseTheme="default" theme={CustomTheme}>
    rest of app
  </CustomizationProvider>
);

Providing Component Elements

Providing Component Elements page anchor

You can set a collection of Component Elements that you want to customize at the Customization Provider level. A Component Element is a DOM node within a component that you can target by name and provide custom CSS for. There maybe one or more exposed Component Elements for any given component within Paste. Component Elements can also be created for your own custom components for your customers to customize.

To read about how to customize components, head to the Customizing Components page.

import {CustomizationProvider} from '@twilio-paste/core/customization';

const MyApp = () => (
  <CustomizationProvider baseTheme="dark" elements={{
    CARD: {
      backgroundColor: 'colorBackground',
      borderRadius: 'borderRadius30',
      borderWidth: 'borderWidth20'
    }
  }}>
    rest of app
  </CustomizationProvider>
)

Implementation Guide

Implementation Guide page anchor

API

API page anchor

Installation

Installation page anchor
yarn add @twilio-paste/customization - or - yarn add @twilio-paste/core

Usage

Usage page anchor
import {CustomizationProvider} from '@twilio-paste/core/customization';
import CustomTheme from ''./themes/theme.json';

const MyApp = () => (
  <CustomizationProvider baseTheme="default" theme={CustomTheme}>
    rest of app
  </CustomizationProvider>
)

Props

Props page anchor
baseTheme?: 'default' (default) | 'dark'

Choose the base theme you would like your application to extend from

customBreakpoints?: string[]

Provide an array of breakpoint sizes that you would like to be able to use in responsive layouts, using the responsive style props

disableAnimation?: boolean

Manually disable all animations in the components using the animation library useful for testing components such as performing visual regression testing

elements?: {[key: string]: PasteCustomCSS}

Supply the Customization Provider an object of Elements that you would like to customize the CSS of. Use the element name provided by Paste as a key and provide any Valid CSS in the Emotion CSS Object format

theme?: Partial<GenericThemeShape>

Provide a full or partial Paste theme to be merged into the base theme that you provide