Flex UI Components
Auto-Generated Documentation for the Flex UI is now available. The auto-generated documentation is accurate and comprehensive, and so may differ from what you see in the official Flex UI documentation.
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 find a component's key
or explore component props, go to Flex UI API Reference.
Agents Desktop View components overview
Teams View components overview
RootContainer
View Full Component Reference >
Direction: Horizontal
MainHeader
View Full Component Reference >
Direction: Horizontal
MainContainer
View Full Component Reference >
Direction: Horizontal
LiveCommsBar
View Full Component Reference >
Direction: Horizontal
NotificationsBar
Direction: Horizontal
Customizing the NotificationsBar is described in Notifications Framework
SideNav
View Full Component Reference >
Direction: Vertical
Agent Desktop View Components
AgentDesktopView
View Full Component Reference >
Direction: Horizontal
AgentDesktopView.Panel1
View Full Component Reference >
Direction: Vertical
AgentDesktopView.Panel2
View Full Component Reference >
Direction: Vertical
CRMContainer
View Full Component Reference >
Direction: Vertical
NoTasksCanvas
View Full Component Reference >
Direction: Vertical
TaskListContainer
View Full Component Reference >
Direction: Vertical
TaskList
View Full Component Reference >
Direction: Vertical
For details on how to configure filters for the task list, see the UI configuration page.
TaskListItem
View Full Component Reference >
Direction: Vertical
Add / Replace / Remove and properties of the TaskListItem are described in the Task Channel Definition API.
TaskListItemButtons
Direction: Horizontal
Add / Replace / Remove and properties of the TaskListItem are described in the Task Channel Definition API.
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
View Full Component Reference >
Direction: Vertical
TaskCanvasHeader
View Full Component Reference >
Direction: Horizontal
TaskCanvasTabs
View Full Component Reference >
Direction: Horizontal
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
View Full Component Reference >
Direction: Vertical
IncomingTaskCanvas
View Full Component Reference >
Direction: Vertical
IncomingTaskCanvasActions
View Full Component Reference >
Direction: Horizontal
CallCanvas
View Full Component Reference >
Direction: Vertical
CallCanvasActions
View Full Component Reference >
Direction: Horizontal
MessagingCanvas
View Full Component Reference >
Direction: Vertical
MessageList
View Full Component Reference >
Direction: Horizontal
MessageList.WelcomeMessage
View Full Component Reference >
Direction: Vertical
MessageListItem
View Full Component Reference >
Direction: Vertical
MessageBubble
View Full Component Reference >
Direction: Vertical
MessageInput
View Full Component Reference >
Direction: Vertical
WorkerDirectory
View Full Component Reference >
Direction: Horizontal
WorkerDirectoryTabs
View Full Component Reference >
Direction: Vertical
The 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>
);
Worker Directory Tabs Hidden Filters
WorkerDirectoryTabs
accepts 2 default props:
hiddenWorkerFilter
hiddenQueueFilter
These filters are applied to the list in combination with the filter applied by the user typing in the search string. You can programmatically apply a filter that is hidden from the user, i.e. the user cannot disable it. You could use this feature to pre-filter the list of available transferees an agent can search and choose from, to their team members or available agents only. In the following example, we use live query to:
- filter the agents list to only show agents with a specific
team_name
attribute (you can set user attributes via your SSO provider) - filter the agents list to only show agents that are in the
Available
activity - filter the queues list to only show queues with a specific
queue_name
attribute
// Filter Agents by Worker Attributes or activity_name
Flex.WorkerDirectoryTabs.defaultProps.hiddenWorkerFilter = 'data.attributes.team_name CONTAINS "sales"'
Flex.WorkerDirectoryTabs.defaultProps.hiddenWorkerFilter = 'data.activity_name CONTAINS "Available"'
// Filter Queues by queue_name or queue_sid
Flex.WorkerDirectoryTabs.defaultProps.hiddenQueueFilter = 'data.queue_name CONTAINS "sales"'
The hidden filter feature is only available in @twilio/flex-ui@1.26.0 and later. Starting in 1.33.3, the hiddenWorkerFilter
has been changed to queueFilter
which takes a predicate function.
Flex.WorkerDirectoryTabs.defaultProps.queueFilter = (queue) => queue.queueName.includes("HR")
ParticipantsCanvas
View Full Component Reference >
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
List mode
ParticipantCanvas
View Full Component Reference >
Direction: Horizontal
ParticipantCanvasListItem
Direction: Vertical
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.
View Full Component Reference >
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: workerSupervisorUserCardSecondLine
- 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
View Full Component Reference >
Direction: Vertical
TaskCard
View Full Component Reference >
Direction: Horizontal
UserCard
Direction: Horizontal
Supervisor.TaskCanvas
View Full Component Reference >
Direction: Vertical
Supervisor.TaskCanvasHeader
View Full Component Reference >
Direction: Vertical
Supervisor.TaskCanvasTabs
View Full Component Reference >
Direction: Horizontal
Worker directory contains 2 tabs by default:
- Overview - key
overview
. Overview Tab has dynamic contant based on the type of task- For standard conference based voice tasks - ParticipantsCanvas
- For messaging tasks - MessagingCanvas
- Info - key
info
. Info tab Contains SupervisorTaskInfoPanel
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
View Full Component Reference >
Direction: Horizontal
WorkerCanvas
View Full Component Reference >
Direction: Vertical
WorkerCanvasHeader
View Full Component Reference >
Direction: Vertical
WorkerProfile
View Full Component Reference >
Direction: Vertical
WorkerSkills
View Full Component Reference >
Direction: Vertical
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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.