Customize Workspace Layout

The Layout settings let you personalize how your Rocket.Chat workspace looks and behaves. You can edit home page content, customize the login page, run custom JavaScript for specific user events, apply custom CSS, and configure user interface options.

Access the Layout settings

You can reach the Layout settings in two ways:

• From the admin menu, go to Manage → Workspace → Settings → Layout.

• From the workspace home screen, click Customize in the top right. This opens the Layout settings directly.

The settings are organized into five collapsible sections: Custom Scripts, Home page content, Login, Custom CSS, and User Interface. Each section is described below in the order it appears in the UI.

Each script and CSS field includes a Full Screen button for easier editing of longer code.

Custom Scripts

The Custom Scripts section lets you execute JavaScript in response to specific events in the workspace. The following settings are available:

For example, the following script triggers a Welcome alert when a logged-in user lands on the /home page:

if(window.location.pathname == '/home'){
    alert("Welcome")
}

The following screenshot shows the result of the script:

Home page content

This section lets you change the content of your workspace home page.

Login

Customize your workspace's login page.

Important:

If you disable the Show Default Login Form option, the login fields are not displayed and you cannot log in with your username/email and password. To re-enable the login form, follow one of these methods.

Method 1: Environment variable

Update your environment variable file by adding OVERWRITE_SETTING_Accounts_ShowFormLogin=true. For details, see Manage Settings Using Environmental Variables.

Method 2: MongoDB shell

• Connect to your Mongo shell and switch to the Rocket.Chat database:

  use rocketchat

• Check the current value of the setting:

  db.rocketchat_settings.findOne({"_id": "Accounts_ShowFormLogin"})

• To disable the form, run:

  db.rocketchat_settings.updateOne({"_id": "Accounts_ShowFormLogin"}, {$set: {'value': false}})

• To enable the form again, run:

  db.rocketchat_settings.updateOne({"_id": "Accounts_ShowFormLogin"}, {$set: {'value': true}})

Custom CSS

In the Custom CSS section, you can define custom CSS to modify your workspace's appearance. Refer to the Customizing Colors guide to learn about the available classes and colors. For a cohesive user experience, we recommend using the variables outlined in the guide. After saving the CSS changes, refresh the page to view the changes to the workspace.

For example, the following CSS snippet changes the color of buttons and secondary elements in rooms and settings:

* {
--rcx-color-button-background-primary-default: #004744;
--rcx-color-button-background-primary-hover: #008079;
--rcx-color-button-background-primary-press: #00756F;
--rcx-color-button-background-primary-focus: #00A59D;
--rcx-color-button-background-primary-keyfocus: #004744;
--rcx-color-button-background-primary-disabled: #B8FFFB;

--rcx-color-button-background-secondary-hover: #008079;
--rcx-color-button-background-secondary-press: #00756F;
--rcx-color-button-background-secondary-focus: #004744;
--rcx-color-button-background-secondary-keyfocus: #004744;
}

The following screenshot shows how a room looks with the CSS customization applied to primary and secondary elements, including hover and press states:

Important

• Customizing the user interface (UI) colors can significantly impact contrast, potentially leading to your UI not meeting WCAG standards. Any color changes you make will apply to all color themes (light, dark, and custom themes).

• While many UI elements can be customized, we strongly recommend focusing your color changes on buttons only, as this enhances brand alignment without disrupting the user experience. We recommend testing the options on a development workspace first.

User Interface

Define the user interface behavior for your workspace. These settings depend on your workspace's Accounts and General settings.