---
title: "Customize the Room Header Toolbox"
slug: "customize-the-room-header-toolbox"
updated: 2026-09-24T19:33:29Z
published: 2026-09-24T19:33:29Z
canonical: "docs.rocket.chat/customize-the-room-header-toolbox"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize the Room Header Toolbox

> [!NOTE]
> **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.

> [!WARNING]
> **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](https://docs.rocket.chat/docs/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

1. Go to **Manage → Workspace → Feature Preview**.
2. 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:

1. Click your avatar and select **Feature preview** under the **Account** section of the menu.
2. Expand the **Room** group.
3. 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.

1. Go to **Manage → Workspace → Settings → Layout → Room Header**.
2. 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.
3. 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:

```json
[
  {
    "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](/docs/customize-the-room-header-toolbox#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 |

> [!WARNING]
> 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.