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

Menu

Expand
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?

Components - add, replace, and remove

Overview of Flex components

Flex UI is a library of programmable or dynamic components that expose a Content property and allows you to add, replace and remove any component and its children.

Content property and add / replace / remove methods

Below you can find a list of UI components and their details, that can be overridden programmatically. This can be done by using add, replace and remove methods with options.

All components must have a key declared.

Syntax for add/replace methods

Flex.Component.Content.add(<MyComponent key="demo-component"/>, {options});
Flex.Component.Content.replace(<MyComponent key="demo-component"/>, {options});

Example

Below is an example of adding a component called AnotherMuteButton to the MainHeader component, aligned to the end (here left) and placed as the first component in front of native components MuteButton and UserControls:

Flex.MainHeader.Content.add(<AnotherMuteButton key="mute"/>, {
  sortOrder: -1, 
  align: end
});

Syntax for remove method

Remove method allows you to remove immediate children of a programmable component by their key.

Flex.Component.Content.remove(key, {options});

Example

Below is an example of removing the AnotherMuteButton component from the MainHeader component. This component is removed by the key we set above, "mute".

Flex.MainHeader.Content.remove("mute");

Options for add/replace/remove methods

if (Expression)

Used in both add and replace methods to add conditions on which component is added or replaced.

Example

Flex.MainHeader.Content.add(<AnotherMuteButton key="mute"/>, {
  if : props => props.task.source.taskChannelUniqueName === "custom1" 
});

sortOrder (number)

Used in add method to specify the order in which the new component is placed in relation to other children of the parent component. Native children components take priority. Sort order counter starts with 0. To always place a new component at the very start or end of the order, use large numbers like -100 or 100, depending on the direction.

Example

Flex.MainHeader.Content.add(<AnotherMuteButton key="mute"/>, {
  sortOrder: -1
});

align ('start' | 'end')

Used in the add method to align new components either to the top/bottom or right/left, depending on the direction of the parent component. Possible values are:

  • start - Aligns new component on the left or top
  • end - aligns new component on the right or bottom

Example

Flex.MainHeader.Content.add(<AnotherMuteButton key="mute"/>, {
  align: end
});

Programmable components

Each immediate child of a component has a key (required for the add and replace methods) and a set of properties that will be inherited by its children. To explore a component's key and props, we recommend using the React developer tools extension for Chrome or Firefox.

Inspecting a component's key

To find a component's key, navigate to the top level of the component in the JSX tree.

Screen Shot 2018-11-28 at 11.32.33.png

Inspecting a component's props

To explore component props, navigate to the DynamicComponent part of the component in the JSX tree.

Screen Shot 2018-11-28 at 11.35.55.png

You can find the description of most properties in the UI Configuration section.

Agents Desktop View components overview

Overview-agentUI_2.png

Teams View components overview

Overview-Supervisor_UI_2.png

RootContainer

Direction: Horizontal

MainHeader

Direction: Horizontal

MainHeader_2.png

MainContainer

Direction: Horizontal

MainContainer-V2.png

LiveCommsBar

Direction: Horizontal

LiveCommsBar.png

NotificationsBar

Direction: Horizontal

Customizing the NotificationsBar is described in Notifications Framework

NotificationBar.png

SideNav

Direction: Vertical

Sidenav.png

Agent Desktop View Components

AgentDesktopView

Direction: Horizontal

AgentDesktopView-V2.png

AgentDesktopView.Panel1

Direction: Vertical

AgentDesktopViewPanel1-v2.png

AgentDesktopView.Panel2

Direction: Vertical

Flex.AgentDesktopView.Panel2

CRMContainer

Direction: Vertical

NoCRM.png

NoTasksCanvas

Direction: Vertical

NoTasksCanvas_v3.png

TaskListContainer

Direction: Vertical

TaskListContainer-v2.png

TaskList

Direction: Vertical

For details on how to configure filters for the task list, see the UI configuration page.

TaskList.png

TaskListitem

Direction: Vertical

Add / Replace / Remove and properties of the TaskListItem are described in the Task Channel Definition API.

Screen Shot 2018-11-28 at 15.18.02.png

TaskListItemButtons

Direction: Horizontal

Add / Replace / Remove and properties of the TaskListItem are described in the Task Channel Definition API.

TaskListItemButtons

Examples

Adding a button to Chat type task

Flex.DefaultTaskChannels.Chat.addedComponents = [{
  target: "TaskListButtons",
  component: <Flex.IconButton key="eye_button" icon="Eye" />
}];

Adding a button to Chat type task when it is in accepted state

Flex.DefaultTaskChannels.Chat.addedComponents = [{
  target: "TaskListButtons",
  component: <Flex.IconButton key="eye_button" icon="Eye" />,
  options: { if: props.task.status === "accepted" }
}];

Removing a reject button from Chat type task

Flex.DefaultTaskChannels.Chat.removedComponents = [{
  target: "TaskListButtons",
  key: "reject"
}];

TaskCanvas

Direction: Vertical

Taskcanvas-v2.width-500.png

TaskCanvasHeader

Direction: Horizontal

Flex.TaskCanvasHeader

TaskCanvasTabs

Direction: Horizontal

Flex.TaskCanvasTabs

Example

Add tabs and content

import { Tab } from "@twilio/flex-ui"

init(flex, manager) {
  const Img = <img src="http://someimage.jpg" />; 

  flex.TaskCanvasTabs.Content.add(
    <Tab icon={Img} iconActive={Img} key="my-new-tab">
      <MyNewTabComponent/>
    </Tab>
  );
}

TaskInfoPanel

Direction: Vertical

Flex.TaskInfoPanel

IncomingTaskCanvas

Direction: Vertical

Flex.IncomingTaskCanvas

IncomingTaskCanvasActions

Direction: Horizontal

IncomingTaskCanvasActions

CallCanvas

Direction: Vertical

CallCanvas-v2.png

CallCanvasActions

Direction: Horizontal

CallCanvasActions

MessagingCanvas

Direction: Vertical

MessagingCanvas-v2.width-500.png

MessageList

Direction: Horizontal

Flex.MessageList

MessageList.WelcomeMessage

Direction: Vertical

MessageList.WelcomeMessage-v2.png

MessageListItem

Direction: Vertical

Flex.MessageListItem

MessageBubble

Direction: Vertical

Flex.MessageBubble

MessageInput

Direction: Vertical

Flex.MessageInput

WorkerDirectory

Direction: Horizontal

WorkerDirectory

WorkerDirectoryTabs

Direction: Vertical

WorkerDirectoryTabs

Worker directory contains 2 tabs by default:

  • Agents - key workers
  • Queues- key queues

Example: Add new custom tab

Flex.WorkerDirectory.Tabs.Content.add(
  <Flex.Tab key="my-tab" label="My Tab">
        <div> "Hello World"
        </div>
  </Flex.Tab>
);

ParticipantsCanvas

Direction: Horizontal

ParticipantsCanvas is a responsive component and will switch between regular mode and list mode depending on the size of the container its placed in. Regular mode and list mode contain different children - ParticipantCanvas and ParticipantCanvasListItem repsectively. When customizing ParticipantsCanvas children, like adding an additional button, remember to do customization to both children components

Regular mode

ParticipantsCanvas

List mode

ParticipantsCanvas in ListMode

ParticipantCanvas

Direction: Horizontal

ParticipantCanvas

ParticipantCanvasListItem

Direction: Vertical

ParticipantCanvas.ListItem

Teams View Components

WorkersDataTable

WorkersDataTable is a programmable component. It is a Material UI table styled to the Flex theme with data from the Insights SDK.

As of flex-ui v1.12.0 new exports were added to refer to workers instead of agents:

  • WorkersDataTable
  • WorkerListFilterSelect
  • WorkersDataTable
  • WorkersDataTableProps
  • WorkerListFilter

For example, AgentsDataTable is now referred to as WorkersDataTable. However, previous exports (like AgentsDataTable) are kept for backwards compatibility

By default, WorkersDataTable contains the following rows:

  • Agent - UserCard component
    • SupervisorUserCardFirstLine - default value retrieves the full name of the worker if it exists, and the identity if not. Variables provided to the template: worker
    • SupervisorUserCardSecondLine - default value shows the availability of the worker. Variables provided to the template: worker
    • The first and second row are template strings with names.
  • Calls -TaskCardList component, showing tasks of the voice channel in assigned and wrapping state
  • Other tasks - TaskCardList component, showing tasks of all channels (apart from voice) in assigned and wrapping state

Add columns to WorkersDataTable

Columns can be added to the table programmatically. Columns cannot be removed yet (the ability to do that is coming soon). You can add columns with different types of content:

  • TaskCardList component
  • Any custom component
  • String

TaskCardList

import { TaskCardList, ColumnDefinition } from "@twilio/flex-ui";

Flex.WorkersDataTable.Content.add(
       <ColumnDefinition key="calls" header={"My Custom Header"} content={(items, context) => <TaskCardList tasks={items.tasks} />} />);


TaskCardList also has a filter prop which can be used here, and which is optional. If the filter prop is not set, all tasks in the list will be rendered:

export interface TaskCardListProps {
   compareFunction?: (a: TaskData, b: TaskData) => number;
   filter?: (task: TaskData) => boolean;
   tasks: TaskData[];
}


Any custom component

import { ColumnDefinition } from "@twilio/flex-ui";

Flex.WorkersDataTable.Content.add(<ColumnDefinition key="hello" header={"Helloxxx"} content={<div>hello</div>}/>);


String

You can use Worker attributes as follows:

import { ColumnDefinition } from "@twilio/flex-ui";

Flex.WorkersDataTable.Content.add(<ColumnDefinition key="team" header={"Team"} content={item => item.worker.attributes.team_name}/>);

Customizing filters

By default, WorkersDataTable has 2 filters:

  • All agents
  • Active agents - worker with current activity state set of type available

Filters for the Workers Table can be programmatically changed, by defining filters property of WorkersDataTable component

Example of creating a filter to show workers with activity "Break"

With configuration object

   componentProps: {
        WorkersDataTable: {
            filters: [
                {
                    query: 'data.activity_name == "Break"',
                    text: "Workers on break"
                }
            ]
        }
    },...

With defaultProps API

Flex.WorkersDataTable.defaultProps.filters = [
                {
                    query: 'data.activity_name == "Break"',
                    text: "Workers on break"
                },...
            ]

Query syntax

Query data schema

data object in the query refers to TaskRouter worker resource. The following attributes on a worker can be used for filters query:

object name

description

format

data.activity_name

worker's current activity friendly name

String

data.attributes

worker's attributes

Key value pair

data.date_activity_changed

date of the last activity change of the current worker

Datetime ISO8601

data.friendly_name

worker's friendly name

String

data.worker_activity_sid

worker's current activity sid

String

data.worker_sid

worker's sid

String

data.workspace_sid

worker's workspace sid

String

Query operators

WorkersDataTable is powered by Twilio Sync and we use Twilio Sync Live Query for filtering of the workers. See Live Query docs for supported query operators.

TaskCardList

Direction: Vertical

TaskCardList.png

TaskCard

Direction: Horizontal

TaskCard.width-800.png

UserCard

Direction: Horizontal

AgentsDataTable.png

Supervisor.TaskCanvas

Direction: Vertical

Supervisor.TaskCanvas

Supervisor.TaskCanvasHeader

Direction: Vertical

Supervisor.TaskCanvasHeader

Supervisor.TaskCanvasTabs

Direction: Horizontal

Supervisor.TaskCanvasTabs

Worker directory contains 2 tabs by default:

Examples

Adding tabs and content

Flex.Supervisor.TaskCanvasTabs.Content.add(
  <Flex.Tab key="my-tab" label="My Tab">
        <div> "Hello World"
        </div>
  </Flex.Tab>
);

SupervisorTaskInfoPanel

Direction: Horizontal

Flex.TaskInfoPanel

WorkerCanvas

Direction: Vertical

WorkerCanvas_2.png

WorkerCanvasHeader

Direction: Vertical

WorkerCanvasHeader.png

WorkerProfile

Direction: Vertical

WorkerProfile_2.png

WorkerSkills

Direction: Vertical

WorkerSkills.png

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.