Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now


Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Overview of Flex UI

Flex UI allows developers to build a custom user experience and custom behaviors for the Flex Agent Desktop and Flex Supervisor Desktop.

Flex User Interface example

The Flex UI Component Library is built in React, and published in NPM. @twilio/flex-ui is a node package that provides all the individual elements of the UI at the component level. It also provides a high-level API to interact with bundled SDKs such as Twilio Client, Programmable Chat and TaskRouter.

This documentation guide gives you an overview of how to:

  1. Programmatically customizing the UI using Plugin Builder or Sample project (for self-hosted, see below)
  2. Configure the UI or manipulate default properties for standard Flex components
  3. Customize themes and styles
  4. Control localization and templates
  5. Add, replace or remove components
  6. Take advantage of UI actions by listening, intercepting and manipulating UI events
  7. Customize agent desktop notifications using Notifications Framework
  8. Alter behavior and appearance for native channels and define custom ones with Task Channel Definition API
  9. Mix-in Task or Theme context to your custom components
  10. Leverage the Flex Manager object to get access and control underlying SDKs

Flex customization models

Flex UI can be programmatically customized by using Plugin Builder (preferred way) or by starting with the sample project. Both ways include @twilio/flex-ui npm package that contains all of the Flex UI components and APIs.

The Plugin approach is required to customize your project running on https://flex.twilio.com, the Flex Application Platform, and simplifies deployment, distribution, and testing of new functionality into your contact center.

If you are just getting started with Flex and do not have specific requirements for hosting the user interface on your own infrastructure, the Plugin approach is strongly recommended. Plugins can still be used when the Flex UI is self-hosted.

Plugin Builder

You can find a description on how to use Plugin Builder here.

Flex UI Sample Project Overview

The sample project demonstrates a quick way to run a standalone React application that contains Flex UI and provides the ability to test out the different programmability options within Flex with examples on configuration, custom components, actions framework, and others. The sample project is available on GitHub - https://github.com/twilio/flex-ui-sample, which is based on create-react-app project.

To get started with the sample project do the following steps:

1. Clone the sample project from GitHub

$ git clone https://github.com/twilio/flex-ui-sample

2. Go to flex-ui sample, install and run the sample project

cd flex-ui-sample
npm install
npm start

3. Your local Flex UI will be running on http://localhost:8080.

Structure of the Sample Project

/ (root directory)

  • Contains various configuration files, notably package.json


  • This holds the assets which will be served by your local webserver
  • appConfig.sample.js is an example of the appConfig.js file you would use for your project. This defines configuration values, such as the Twilio Account linked with Flex.


  • Contains the main files you will customize to build your application
  • App.js file is the top-level component that hosts the Flex UI via <Flex.RootContainer />. Start with this file to explore customizing Flex UI
  • index.js initializes Flex UI with default configuration and mounts App.js


This is the entry file of your application, and it will look something like:

import React from 'react';
import * as Flex from '@twilio/flex-ui';

export default class App extends React.Component {
  render() {
    const { manager } = this.props;

    if (!manager) {
      return null;

    return (
      <Flex.ContextProvider manager={manager}>
        <Flex.RootContainer />
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.