The Flex UI

The 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

Auto-Generated Documentation for the Flex UI is now available as a beta distribution. The auto-generated documentation is accurate and comprehensive, and so may differ from what you see in the official Flex UI documentation.

The Flex UI Component Library is built in React and published on 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 customize 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 the Flex Application Platform,, and simplifies deployment, distribution, and testing of new functionality in 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, we strongly recommend the Plugin approach. Plugins can still be used on a self-hosted Flex UI.

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 containing the Flex UI and provides the ability to test out the different programmability options within Flex. It includes examples on configuration, custom components, actions framework, and others. The sample project is available on GitHub, and is based on the create-react-app project.

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

1. Clone the sample project from GitHub

$ git clone

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.

Thank you for your feedback!

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

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more