Override Flex UI 2.x.x themes, branding and styling

(information)

Info

Auto-Generated Documentation for the Flex UI is now available. The auto-generated documentation is accurate and comprehensive and may differ from what you see in the official Flex UI documentation. It includes a comprehensive overview of Theme options.

The Flex UI exposes 3 main levels of customization:

Base Themes: Flex UI 2.x.x supports two themes: Dark and Light.
Base Theme Color Overrides: Global color overrides that are inherited by all Flex UI components.
Component Theme Overrides: Granular color overrides that allow you to customize a specific component.

(information)

Info

If you're migrating from Flex UI 1.x.x, 2.x.x has a new configuration key called config.theme.

You can achieve these three levels of customization by updating the Flex theme configuration via config.theme. config.theme is defined by the following interface:

1interface ThemeConfigProps {
2   isLight?: boolean; // Represents if light or dark theme
3   tokens?: Tokens; // Paste tokens
4   componentThemeOverrides?: Object; // Object containing component style overrides
5}
6

Where:

Tokens: For usage documentation, see Create a custom theme using the Paste Theme Designer.

componentThemeOverrides: For a list of components you can override, see Flex UI API Reference.

Defining your theme

Base themes

Base themes provide a set of colors as a starting point for your contact center. Flex UI has two themes:

Light
Dark

Configuring a base theme

You can configure the desired base theme in the Flex configuration object.

1const configuration = {
2        theme: {
3            isLight: false
4        }
5};
6
7Flex.manager.updateConfig(configuration);
8

Overriding base theme colors

You can also create your own variation of a theme by passing Paste token values. For Tokens documentation and details on how to generate them, see Create a custom theme using the Paste Theme Designer.

1const configuration = {
2      theme: {
3        isLight: false,
4        tokens: {
5          backgroundColors: {
6            colorBackground: "rgb(255, 0, 0)",
7          },
8          "textColors": {
9            "colorText": "rgb(0, 0, 255)",
10          }
11        }
12      }
13    };
14
15Flex.manager.updateConfig(configuration);
16

Overriding individual components

Flex theming also supports granular customizations at the individual component level. In the following code sample, Flex will override the MainHeader background color and text color, as well as the SideNav background color and icon background color.

1const configuration = {
2    theme: {
3        componentThemeOverrides: {
4            MainHeader: {
5                Container: {
6                    background: "#ff0000",
7                    color: "#00ff00"
8                }
9            },
10            SideNav: {
11                Container: {
12                    background: "#4a4e60"
13                }
14                Icon: {
15                    background: "#4a4e60"
16                },
17            }
18        }
19    }
20};
21
22Flex.manager.updateConfig(configuration);
23

See the complete list of customizable components and properties.

Applying your theme

Once you've defined a theme, you'll need to apply it to Flex UI.

Applying your theme in a Flex Plugin

Define your color theme by specifying a Boolean value for isLight, along with optional tokens and component overrides.

CustomTheme.js

1const configuration = {
2      theme: {
3        isLight: false,
4        tokens: {
5          backgroundColors: {
6            colorBackground: "rgb(255, 0, 0)",
7          },
8          "textColors": {
9            "colorText": "rgb(0, 0, 255)",
10          }
11        },
12        componentThemeOverrides: {
13          MainHeader: {
14              Container: {
15                  background: "#ff0000",
16                  color: "#00ff00"
17              }
18          },
19          SideNav: {
20              Container: {
21                  background: "#0000ff"
22              },
23              Icon: {
24                  background: "#ffc300",
25                  color: "#ff5733"
26              },
27          }
28        }
29      }
30}
31
32Flex.manager.updateConfig(configuration);

Then set your custom theme inside the Flex configuration and apply it during plugin initialization.

ThemePlugin.js

1export default class ThemePlugin extends FlexPlugin {
2
3  init(Flex, Manager) {
4    const configuration = {...};
5
6    // apply theme
7    Manager.updateConfig(configuration);
8  }
9}
10

Applying themes to self-hosted installations of Flex

Include your custom theme in the configuration object's theme property when initializing Flex.

1// refer to previous examples for setting your theme configuration
2const configuration = {...}; 
3
4Twilio.Flex.runDefault(configuration);
5

Next Steps

Explore the full reference of configurable theme properties
Write a plugin to customize your Flex theme
Start changing the behavior of the Flex UI with the Actions Framework