Documentation | 2025.1

# CSS & JavaScript

Custom CSS and JavaScript files will be loaded automatically, following a browser refresh, if you place them under either:

- SWARM_ROOT/public/custom/*.(css|js)

or

- SWARM_ROOT/public/custom/sub-folder/*.(css|js)

- Swarm only supports customizations placed directly within the `SWARM_ROOT/public/custom` folder or one sub-folder down. Customizations are added after all standard CSS and JavaScript. If more than one custom file is present, they are added in alphabetical order.

- Before creating any customizations, make sure that the `SWARM_ROOT/public/custom` folder exists. Swarm does not ship with or create this folder.

- When you add custom CSS or JavaScript to Swarm, only a browser refresh is required. You do not need to restart apachectl.

- If you have checked the custom CSS or JavaScript code for accuracy and it still doesn't work after a browser refresh, check the folder permissions for the folder the customization is in.

## Sample JavaScript extensions

The following is an example JavaScript customization that you might wish to apply to your Swarm installation. JavaScript customizations can be implemented separately, but ideally, you would apply the JavaScript customizations in a single file to reduce the number of web requests required.

Coding errors in your custom JavaScript files could cause the Swarm UI to stop working. If this occurs, use your browser's development tools to identify which file contains the problem, and move that file out of the `SWARM_ROOT/public/custom` folder. When the problem has been resolved, the file can be returned.

### Add text to the Log in dialog

This customization can only be used if require_login is set to true, see Require login.

    // Custom js to put text into the login box
    $(function() {
        setTimeout(function () {
                if ($('.login-form')) {
                    $('.form-body')
                        .prepend("<b style='padding-bottom: 20px; display: inline-block'>Please use your Helix Core Server login credentials.</b>");
                    $('.form-body button').html('Login with Helix Core Server credentials');
                }
            },
            800);
    });

Replace the Please use your Helix Core Server login credentials with the text you want to add to the top of the Swarm log in dialog.

Save this line in a file, perhaps `customize-login-text.js`, within the `SWARM_ROOT/public/custom`. Swarm automatically includes the JavaScript file, adding the text to the top of the log in dialog immediately for subsequent log ins.

## Sample CSS customizations

The following are example CSS customizations that you might wish to apply to your Swarm installation. Each example can be implemented separately. Ideally, you would apply the CSS customizations in a single file to reduce the number of web requests required.

If your Swarm administrator has configured Swarm to connect to more than one Helix Core Server instance you can customize Swarm for each server instance it is connected to. For instructions on customizing Swarm for individual Helix Core Server instances, see CSS customization when Swarm is connected to multiple Helix Core Server instances.

### Adjust the default tab size

    body {
       tab-size: 4;
    }

Replace the `4` with the tab size you prefer.

Save these lines in a file, perhaps `tab-size.css`, within the `SWARM_ROOT/public/custom` folder. Swarm automatically includes the CSS file, adjusting the tab size immediately for subsequent page views.

### Apply a custom background to the login screen

    .session-container .modal-overlay.login::after {
        background-image: url('/custom/login_background.jpg');
        background-position: top center;
        background-size: 100%;
    }

Replace the `/custom/login_background.jpg` URL fragment with the image you want to use. If you do not specify a full URL, the image you specify must exist within the `SWARM_ROOT/public` folder, preferably within the `SWARM_ROOT/public/custom` folder.

Save these lines in a file, perhaps `login-background.css`, within the `SWARM_ROOT/public/custom` folder. Swarm automatically includes the CSS file, immediately replacing the login screen's background for subsequent page views.

### Replace Swarm's logo in the main navigation bar

    #react-swarm-app-container .primary.navigation .swarmLogo a svg{
        display:none;
    }
    #react-swarm-app-container .primary.navigation .swarmLogo a  {
        background-repeat: no-repeat;
        background-image: url('/custom/navbar_logo.jpg');
        background-size: 116px 25px;
        background-position: 15px center;
        background-clip: content-box;
    }

Replace the `/custom/navbar_logo.jpg` URL fragment with the image you want to use. If you do not specify a full URL, the image you specify must exist within `the SWARM_ROOT/public` folder, preferably within the `SWARM_ROOT/public/custom` folder.

Save these lines in a file, perhaps `navbar-logo.css`, within the `SWARM_ROOT/public/custom` folder. Swarm automatically includes the CSS file, immediately replacing the Swarm logo for subsequent page views.

Swarm's navbar design supports logos up to 24 pixels tall. Even if your logo fits within that height, you may need to also adjust the width, height, margins, or padding to suit your logo.

### Adjust the appearance of avatars

The Swarm UI is changing and moving toward using React, currently there is a mix of React and legacy PHP controlling the UI. This means that there are currently two methods of rendering avatars and you need to customize both.

- For avatars rendered by Swarm using PHP, see Adjust avatar appearance when rendered by PHP

- For avatars rendered by Swarm using React, see Adjust avatar appearance when rendered by React

For instructions on adding custom avatars, see Add custom avatars

#### Adjust avatar appearance when rendered by PHP

    img.avatar {
        border: 2px dashed red;
        border-radius: 10%;
    }

You can make a number of adjustments to the way Swarm presents avatars rendered by PHP, such as adding a border and adjusting the border radius, as the example above demonstrates. You should avoid attempting to set specific sizes because Swarm uses different sizes depending on where the avatar is displayed.

Save these lines in a file, perhaps `avatars.css`, within the `SWARM_ROOT/public/custom` folder. Swarm automatically includes the CSS file, immediately changing the appearance of avatars for subsequent page views.

#### Adjust avatar appearance when rendered by React

    #react-swarm-app-container .userAvatar img{
        border: 2px dashed red;
        border-radius: 10%;
    }

You can make a number of adjustments to the way Swarm presents avatars rendered by React, such as adding a border and adjusting the border radius, as the example above demonstrates. You should avoid attempting to set specific sizes because Swarm uses different sizes depending on where the avatar is displayed.

Save these lines in a file, perhaps `avatars-react.css`, within the `SWARM_ROOT/public/custom` folder. Swarm automatically includes the CSS file, immediately changing the appearance of avatars for subsequent page views.

#### Add custom avatars

Custom avatars for individual users or groups are added to Swarm using custom CSS. Custom avatars are intended for use with system users and groups.

> To add a custom avatar for a user:

>     img.avatar[data-user="<userid>"], .userAvatar img[alt="<user name>"]{
>         content: url(<path to avatar>);
>     }

> To add a custom avatar for a group:

>     img.avatar[data-user="<groupid>"], .userAvatar img[alt="<group name>"]{
>         content: url(<path to avatar>);
>     }

Save these lines in a file, perhaps `avatars-custom.css`, within the `SWARM_ROOT/public/custom` folder. Swarm automatically includes the CSS file, immediately using your custom avatars for subsequent page views.

### Add a custom icon to a menu item

When you create a custom menu item in the menu_helpers configuration block, you can specify the menu icon to use in the Swarm CSS.

Add some custom CSS to Swarm to replace the default icon with a custom icon for the menu item. For example, the CSS below replaces the default icon with the double-speech-bubbles.svg icon for the custom01 menu item by modifying the svg.svgIcon.custom01MenuIcon and .menuItem-custom01 classes:

    .swarmMenu .menuItem.menuItem-tests .svgIcon{
        display:none;
    }.swarmMenu .menuItem.menuItem-tests a::before{
        content: '';
        background-image: url('/swarm/img/icons/line/double-speech-bubbles.svg');
        background-size: 16px;
        background-repeat: no-repeat;
        padding-left: 20px;
            padding-right: 4px;
            margin-left: 20px;
    }

Save these lines in a file, perhaps menu_custom01.css in a folder called custom_menus, in the SWARM_ROOT/public/custom folder. Swarm automatically includes the CSS file, immediately using your custom menus for subsequent page views. If you are using your own custom images, we recommend you store them in the same folder as your custom css.

## CSS customization when Swarm is connected to multiple Helix Core Server instances

If Swarm is configured to connect to more than one Helix Core Server instance, Swarm can be customized for each of the Helix Core Server instances it is connected to. This gives users an simple visual prompt as to which Helix Core Server instance they are currently viewing in Swarm. All of the customizations described in the section above are available for multiple Helix Core Server instances.

- The Swarm Global Dashboard cannot be customized.
- For instructions on how to configure Swarm to connect to multiple Helix Core Server instances, see Multiple Helix Core Server instances.

To customize Swarm for a Helix Core Server instance, include the [data-server-id="<server-name>"] data attribute in the CSS selector you are customizing. Replace <server-name> with the Helix Core Server name the customization is for.

To apply a customization to all Swarm Helix Core Server instances, don't include the data attribute in the CSS selector you are customizing.

See the examples below to see how the data attribute is used to customize Swarm for the individual Helix Core Server instances. As with the customization of Swarm when it is connected to a single Helix Core Server, you should ideally apply the CSS customizations in a single file to reduce the number of web requests required.

### Apply a custom background color to the navigation bar of each of the Helix Core Server instances

    body[data-server-id="serverA"] #react-swarm-app-container .swarm-navigation {
        background-color: #d21544;
    }
    body[data-server-id="serverB"] #react-swarm-app-container .swarm-navigation {
        background-color: pink;
    }

### Apply custom background images to the login screen of each of the Helix Core Server instances

    body.route-login[data-server-id="serverA"] .session-container .modal-overlay.login::after {
        background-position: top center;
        background-size: 100%;
        background-image: url(/custom/login_background_A.jpg);
    }
    body.route-login[data-server-id="serverB"] .session-container .modal-overlay.login::after {
        background-position: top center;
        background-size: 100%;
        background-image: url(/custom/login_background_B.jpg);
    }

Your search for returned results