Customize the Room Header Toolbox

This feature is available from Rocket.Chat 8.9.0

The room header toolbox is the row of action icons at the top of a room, such as Threads, Members, and Discussions. With the Room Toolbox Layout setting, workspace administrators can choose which actions appear in the header, set their order, and decide how many stay visible before the rest collapse into the kebab menu (⋮). The layout is defined in JSON and can differ for public channels, private channels, and direct messages.

Room Toolbox Layout is a feature preview. A workspace administrator must enable feature previews, and each user must then turn the option on for their own account. Feature previews are still being tested, so their behavior may change in future releases. Refer to Feature Preview for details.

Prerequisites

Room Toolbox Layout is available on all plans, including Community.

A custom layout takes effect only when both of the following are enabled.

Allow feature previews in the workspace

Go to Manage → Workspace → Feature Preview.
Enable Allow Feature Preview.

The same toggle is also available under Manage → Workspace → Settings → Accounts. Until Allow Feature Preview is enabled, the Room Toolbox Layout setting in the Layout settings appears inactive and you can't edit it.

Turn on Room Toolbox Layout for your account

Each user who wants the custom layout must enable it themselves:

Click your avatar and select Feature preview under the Account section of the menu.
Expand the Room group.
Enable Room Toolbox Layout.

Users who leave this off keep the default toolbox, whatever the workspace configuration.

Configure the layout

Once both toggles are on, define the layout in the Layout settings. You write the layout as JSON, with one entry per room type or group of room types you want to customize.

Go to Manage → Workspace → Settings → Layout → Room Header.
In Room Toolbox Layout, enter a JSON array. Each entry names the room types it applies to and describes the layout for those rooms. The setting's description includes a sample configuration you can paste and adapt.
Click Save changes.

In the following example, public and private channels pin Members to the left of the divider and show up to three other actions before collapsing the rest. Direct messages show one action and collapse everything else:

[
  {
    "roomType": ["c", "p"],
    "maxVisibleNormal": 3,
    "items": [
      { "id": "members-list", "featured": true, "order": 1 }
    ]
  },
  {
    "roomType": ["d"],
    "maxVisibleNormal": 1
  }
]

Field reference

Each entry in the array can use the following fields. Only roomType is required; the others fall back to the defaults described below.

Field	Description
`roomType`	The room types the entry applies to: `c` (public channels), `p` (private channels), and `d` (direct messages). You can combine several types in one entry, as in `["c", "p"]`, or give each its own entry. Each room type can appear in only one entry. Room types you don't list keep the default toolbox.
`items`	The actions to configure, each identified by its `id`. See Action IDs for the values to use. Actions you don't list are placed after the ones you do, in their default order.
`items[].featured`	Set to `true` to pin the action to the left of the divider, apart from the other actions. Some actions, such as Video call, are featured by default; set this to `false` on them to move them into the regular row.
`items[].order`	The action's position among actions in the same group, featured or not. Lower numbers come first.
`maxVisibleNormal`	How many non-featured actions stay in the header. Any beyond this number move to the kebab menu. Defaults to `6`. Set it to `0` to move all non-featured actions into the kebab menu.

On narrower windows, where the header has less room, all non-featured actions move into the kebab menu and only featured actions stay in the header.

Action IDs

Use these IDs in items[].id. Which actions a room shows depends on the room type, the workspace settings, and each member's permissions, so not every ID appears in every room. An ID for an action that isn't present in a room has no effect there.

ID	Action (tooltip label)
`members-list`	Members (Teams Members in a team)
`thread`	Threads
`discussions`	Discussions
`uploaded-files-list`	Files
`mentions`	Mentions
`starred-messages`	Starred Messages
`pinned-messages`	Pinned Messages
`rocket-search`	Search Messages
`channel-settings`	Room Information
`team-info`	Team info
`team-channels`	Team Channels
`user-info`	User Info (direct messages)
`user-info-group`	Members (direct messages with several people)
`push-notifications`	Notifications Preferences
`autotranslate`	Auto-Translate
`export-messages`	Export messages
`clean-history`	Prune Messages
`banned-users`	Banned Users
`e2e`	Enable E2E encryption or Disable E2E encryption
`calls`	Calls
`start-video-call`	Video call (featured by default)
`start-voice-call`	The voice call action in direct messages (featured by default)
`outlookCalendar`	Outlook calendar
`game-center`	Game Center

Actions added by apps always stay in the kebab menu. They can't be featured, reordered, or shown in the header.

Validation

The value is checked against a schema when you save. Saving fails with an error if the value:

isn't valid JSON,
is an empty array, or has an entry without roomType,
uses a field the schema doesn't recognize,
gives a field the wrong kind of value, such as a negative or decimal maxVisibleNormal, or an empty id,
references an unsupported room type, or
lists the same room type twice, whether in one entry or in more than one.

When saving fails, the previously saved value stays in effect. To go back to the default toolbox for every room type, clear the field and save.

Fallback behavior

A room type keeps its default toolbox if any of the following is true:

Allow Feature Preview is off for the workspace, or the user hasn't enabled Room Toolbox Layout in their feature preview settings.
The Room Toolbox Layout setting is empty.
No entry in the array covers that room type.