White-Labeling Mango: Custom Branding and Logos

Overview

White-labeling replaces Mango by Radix IoT’s default branding with your own company identity: the color theme, the two logos, the browser tab icon and title, the fonts, the login page and the menu labels. Whether you are an integrator deploying Mango for end clients or an organization that wants a consistent brand experience, this guide covers the full workflow. Almost everything here applies to the whole instance, so every user sees the same branding; Step 6 covers what can differ per client.

Prerequisites

• Mango 5.x and a superadmin account (the JSON store and File stores pages are superadmin-only)
• Your logo as PNG or SVG with a transparent background: a full version for the login page, which shows it at up to 300 × 150 px, and a compact version for the sidebar header
• Tab icon files made from your logo: a favicon.ico, a 32 × 32 and a 16 × 16 PNG, and a 180 × 180 PNG for iOS home screens
• Your brand color hex codes, if you will define a custom palette
• File system access to the Mango server, for the tab icon
• Basic CSS knowledge, for Steps 4 and 5

Step 1: Customize the Color Theme

Mango’s UI is built on Angular Material. Its colors come from a theme: four palettes (primary, accent, warning and background) plus a light or dark setting. Mango’s built-in themes cannot be edited, so you add your own.

Build a Theme from the Available Palettes

1. Navigate to Platform management > UI settings
2. On the Choose color scheme card, click Add new theme, enter a name (letters, digits and underscores, starting with a letter) and click OK. The new theme becomes the Default color theme
3. Click the pencil (Edit theme) icon beside Default color theme. The Edit theme dialog opens
4. Choose a palette for each of Primary palette, Accent palette, Warning palette and Background palette:
   • Primary — the toolbar, the sidebar and primary buttons
   • Accent — floating action buttons, toggles and highlights
   • Warning — alerts and error states
   • Background — page and card backgrounds
5. Tick Dark theme for a dark version, with a dark background and light text
6. Click OK, then Save at the top of the page, and refresh the browser

The palette lists hold Angular Material’s 19 built-in palettes (red through blue-grey), Mango’s own palettes and any you define below. The dialog shows each chosen palette’s colors, and Show all hues displays its full range of shades. To change the theme later, select it under Default color theme and click the same pencil icon.

To let each viewer’s browser or operating system choose between light and dark, tick Use browser preferred color scheme. Mango then switches between the Default color theme and the theme in the field the box reveals, Alternate theme (dark) or Alternate theme (light).

Define a Custom Palette

If none of the palettes matches your brand, define your own:

1. Navigate to Platform management > JSON store
2. Open the mangoUI-settings entry, which holds the UI settings
3. Add a palettes object at the top level of its JSON. A palette must define all fourteen shades, 50 to 900 plus A100, A200, A400 and A700:

{
    "palettes": {
        "myBrandBlue": {
            "50": "#e3f2fd",
            "100": "#bbdefb",
            "200": "#90caf9",
            "300": "#64b5f6",
            "400": "#42a5f5",
            "500": "#1e88e5",
            "600": "#1565c0",
            "700": "#0d47a1",
            "800": "#0a3d91",
            "900": "#082e6b",
            "A100": "#82b1ff",
            "A200": "#448aff",
            "A400": "#2979ff",
            "A700": "#2962ff"
        }
    }
}

4. Save the entry and refresh the browser. Palettes are loaded when the UI starts, so a new one appears only after a refresh
5. In Platform management > UI settings, open your theme’s Edit theme dialog. myBrandBlue is now in the palette lists
6. Select it, click OK, and click Save

Step 2: Replace the Logos

Mango has two logo settings, and they appear in different places:

(When Use browser preferred color scheme is ticked and a viewer’s browser prefers the alternate theme, the login page shows the alternate logo too.)

Set the Login Page Logo

1. Navigate to Platform management > UI settings
2. On the Choose color scheme card, click the paper clip icon beside Default logo URL. The Choose file dialog opens on the public file store
3. Click Create new folder and name it branding (or open a folder you already have), then click Upload files and upload your logo
4. Select the file and click OK. The field fills with its URL, /rest/latest/file-stores/public/branding/my-company-logo.png
5. Click Save

You can also upload the files beforehand at Platform management > File stores, into the public store.

Set the Sidebar Logo

The alternate logo’s field is hidden until you tick a box:

1. On the same card, tick Use browser preferred color scheme. Two more fields appear, Alternate theme (dark) and Alternate logo (dark). They read (light) instead when your default theme is a dark one
2. Click the paper clip beside the alternate logo field and choose your sidebar logo the same way. The sidebar header is 130 px tall, so a compact or square version of your logo works best
3. If you do not want Mango to switch themes with each viewer’s light or dark preference, untick Use browser preferred color scheme again. The alternate logo stays set
4. Click Save

Alternatively, set both logos in the mangoUI-settings JSON store entry:

{
    "logoSrc": "/rest/latest/file-stores/public/branding/my-company-logo.png",
    "alternateLogo": "/rest/latest/file-stores/public/branding/my-company-icon.png"
}

Step 3: Replace the Browser Tab Icon

Every page of the Mango UI links four icon files from the UI module: favicon.ico, icon32.png (32 × 32), icon16.png (16 × 16) and apple-touch-icon.png (180 × 180, used when the UI is added to an iOS home screen). Browsers choose among them, so replace all four. There is no UI setting for them. Instead, you place your own copies in Mango’s overrides folder, which Mango checks before its own files.

1. Create the four files from your logo, with exactly these names and sizes
2. On the server, create the folder overrides/web/modules/mangoUI/web/img/ inside the Mango data directory. That is the installation directory, unless paths.data in mango.properties points elsewhere
3. Copy the four files into it
4. Restart Mango
5. Clear your browser cache, or check in a private window. Mango serves these icons with a one-year cache lifetime under an unchanged URL, so a browser that has already loaded the old icon keeps showing it

Step 4: Apply Your Fonts and a Custom Stylesheet

Fonts

The Fonts card of UI settings has Default font, Heading font, Paragraph font and Code font (fixed width). Each takes a CSS font-family value such as 'Inter'. The browser must be able to load the font, so for a web font add its @import line to the stylesheet below.

User Stylesheet

1. Navigate to Platform management > UI settings
2. On the Miscellaneous settings card, click the paper clip icon next to User stylesheet URL. It also opens the public store
3. Open your branding folder, click Create new file and name it brand-styles.css. The file opens in the editor
4. Add your custom CSS:

/* @import must come before every other rule, or the browser ignores it */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;700&display=swap');

/* The login page background (the page's container carries the class "login") */
.main-application.login {
    background-image: url('/file-stores/public/branding/login-bg.jpg');
    background-size: cover;
    background-position: center;
}

/* The toolbar across the top of every page */
md-toolbar.ma-ui-main-toolbar {
    background-color: #1565c0 !important;
}

/* The sidebar header, behind the sidebar logo */
md-toolbar.ma-ui-sidebar-header {
    background-color: #0d47a1 !important;
}

/* Card title rows */
md-card > md-card-title {
    border-bottom: 2px solid #0d47a1;
}

5. Click OK. It saves the file and fills the field
6. Click Save on the UI settings page, then refresh the browser

The stylesheet loads on every page, the login page included, which is why it and its images belong in the public store, referenced by their /file-stores/public/... URLs.

Step 5: Replace Text in the Menu, the Login Page and the Browser Tab

Menu Labels

1. Go to Platform management > Edit menu
2. Click the edit (pencil) icon on a menu item. The same page also lets you reorder items by their drag handle and add new ones with the + button, and the item dialog’s Show menu item box hides or shows an item
3. Change Menu text. It takes precedence over Menu text translation key, a separate field for a translation key
4. Click Save in the dialog, then Save on the Edit menu page, and reload the browser

Login Page Heading

The login card’s heading reads Please login. To replace it, add this to your user stylesheet:

/* Hide the default heading */
.main-application.login md-card-title .md-headline {
    font-size: 0;
    line-height: 0;
}

/* Show your own text in its place */
.main-application.login md-card-title .md-headline::after {
    content: 'MyCompany Building Management';
    font-size: 24px;
    line-height: 1.4;
    display: block;
}

Browser Tab Title

The browser tab shows the page name, a dash, and the titleSuffix UI setting, which is Mango by default. The UI settings page has no field for it; set it in the mangoUI-settings JSON store entry:

{
    "titleSuffix": "MyCompany BMS"
}

The login page’s tab then reads Login - MyCompany BMS, and every other page follows the same pattern.

Step 6: Per-Client Content on Custom Pages (Multi-Tenant)

The theme, the logos, the stylesheet and the tab title are the same for every user of an instance, and the login page appears before Mango knows who is logging in. If you serve several clients from one Mango instance, what you can vary per client is the content of your custom pages:

1. Create a role for each client: in Access management > Users, on the Roles card, click Add role. Give each client’s users their client’s role
2. Put each client’s branding in its own folder of the public store. Anything in public can be read without a login, so keep only branding there
3. In the page’s markup (Platform management > Edit pages), show content by role:

<img ng-if="User.current.hasRole('clientA')"
     src="/file-stores/public/branding/clientA/logo.png">

<img ng-if="User.current.hasRole('clientB')"
     src="/file-stores/public/branding/clientB/logo.png">

4. Use ng-class or ng-style with the same test to vary colors within the page

hasRole takes a role’s XID and counts inherited roles. A superadmin passes every hasRole check, so an administrator sees both logos.

Verification

Confirm your branding is applied correctly:

• The theme’s colors match your brand guidelines, in both schemes if you ticked Use browser preferred color scheme
• The login page shows your default logo, and the sidebar shows your alternate logo
• The browser tab shows your icon and your title (check in a private window)
• Your fonts load (the browser console reports font loading errors)
• The login page background and heading match your design (log out to check)
• Menu labels display your custom text
• Everything persists after a browser restart and a Mango restart

Troubleshooting

The UI stops loading after you add a palette

• The page shows Error bootstrapping Mango UI app, and Show stack trace names the missing shade
• Remove the palette through the REST API as described in Step 1, fix it, and add it again

Custom palette does not appear in the palette lists

• Refresh the browser after saving the JSON store entry; palettes load when the UI starts
• Check that palettes sits at the top level of the mangoUI-settings JSON, not inside another key

The login page shows your logo but the sidebar does not

• The sidebar uses the alternate logo, not Default logo URL. Set it as in Set the Sidebar Logo

Logo does not display

• Check the URL in UI settings matches the file’s path in the store exactly (case-sensitive)
• Open the URL directly in the browser to confirm the file is there
• Ensure the image format is supported (PNG, SVG, or JPG)
• If the logo shows after login but not on the login page, move the file to the public store

CSS styles not applying

• Confirm the User stylesheet URL is saved in UI settings
• An @import anywhere but the top of the file is ignored, and so is the font it loads
• Use browser developer tools to check whether another rule overrides yours; add !important if needed
• Clear the browser cache to ensure the latest CSS file is loaded

Tab icon does not change

• Check the folder, overrides/web/modules/mangoUI/web/img/ inside the Mango data directory, and that the file names match exactly
• Restart Mango
• Open http://your-server:8080/ui/img/icon32.png directly. If it shows your icon, the server side is done and only the browser’s cache is stale: clear it, or check in a private window