Skip to main content

Pentaho+ documentation has moved!

The new product documentation portal is here. Check it out now at


Hitachi Vantara Lumada and Pentaho Documentation

Customize the Pentaho User Console

Parent article

You can change the look and feel of the Pentaho User Console (the standard web application for the Pentaho Server) by manually editing its configuration files, graphics, and CSS style sheets. Through these files and style sheets, you can also change interactive elements of Report Designer, Analyzer, and Dashboard Designer. For example, you can change the User Console’s default theme from Ruby to Sapphire or Crystal, then examine the style definitions to customize the login page.

Note If you need to configure or manage Pentaho Server users and their roles, as opposed to changing its style, use the Pentaho administration page of the console.

Before editing any elements in the Pentaho WAR file, you must stop the web application server on which you are running the Pentaho software.

Location of customizable configuration files

Mantle style CSS

This is the structural cascading style sheet for the Pentaho User Console. It inherits some elements from the Widgets.css file in the same directory, so you may need to look at that as well. Modifying these styles could have dramatic impact on Pentaho User Console rendering.


Theme-specific local and global style sheets for PUC

These directories contain style sheets and other theme materials for each Pentaho Server client tool.

File NameLocationDescription
globalRuby.css/server/pentaho-server/pentaho-solutions/system/common-ui/resources/themes/ruby/This is the main structural, theme-specific style sheet for the default theme for the User Console (Ruby).
mantleRuby.css/server/pentaho-server/tomcat/webapps/pentaho/mantle/themes/ruby/This is the customizable presentation portion of the theme style sheet for the default theme for the User Console (Ruby).
globalCrystal.css/server/pentaho-server/pentaho-solutions/system/common-ui/resources/themes/crystal/This is the main structural, theme-specific style sheet for an alternate theme for the User Console (Crystal).
mantleCrystal.css/server/pentaho-server/tomcat/webapps/pentaho/mantle/themes/crystal/This is the customizable presentation portion of the theme style sheet for an alternate theme for the User Console (Crystal).

Product-specific theme settings for Analyzer, Dashboard Designer, and Interactive Reports

These directories contain style sheets and other theme materials for each.

Set the <cache>false</cache> in pentaho-solutions/system/common-ui/settings.xml while customizing these plugins. Otherwise, the changes are not visible without a server restart.

Product NameLocationDescription
Analyzerpentaho-solutions/system/analyzer/styles/themes/Style sheets and theming materials for Analyzer.
Interactive Reportspentaho-solutions/system/pentaho-interactive-reporting/resources/web/themes/Style sheets and theming materials for Interactive Reports.
Dashboard Designerpentaho-solutions/system/dashboards/resources/themes/Style sheets and theming materials for Dashboard Designer.

Change the application login page logo and background

You can edit the User Console login page to replace the default logo with your corporate logo or other image. You can also modify or replace the default background image and other page elements to better fit your organization or brand.

User console logo and background elements

NoteThe User Console login page uses CSS properties that start with "#login" for easy identification. The method for changing the logo and background for other available themes, like Crystal and Sapphire, is the same. Each theme uses different style definitions, image types, names, and file paths.

Follow the steps below to change the default logo and background images for the User Console login page theme.


  1. Back up and remove the default image file for the logo from the /pentaho-server/pentaho-solutions/system/common-ui/resources/themes/<theme-name>/images directory of the theme you want to change.

    Ruby (default)header_logo.svg
  2. Rename the new image file to match the name of the logo file that you are replacing, and then copy the new image file into the \pentaho-server\pentaho-solutions\system\common-ui\resources\themes\<theme-name>\images directory.

  3. Update the style definitions for your image. Navigate to the \pentaho-server\pentaho-solutions\system\common-ui\resources\themes\<theme name> directory for the theme you are changing and then open the .css file with a text editor.

    Ruby (default)globalRuby.css
  4. Locate the #login-header-logo property, then adjust the dimensions and margin for the new image.

  5. (Optional) You can back up and remove the background image file. If not replacing the background image, proceed to the next step.

    The background image file is located in the \pentaho-server\pentaho-solutions\system\common-ui\resources\themes\<theme-name>\images directory of the theme you want to change. Use the following table to locate your theme and image.
    Ruby (default)bg.svg
    1. Rename the new background image file to match the name of the background file that you are replacing, and then copy the new image file into the \pentaho-server\pentaho-solutions\system\common-ui\resources\themes\<theme-name>\images directory.

    2. Update the image dimensions for your background. Navigate to the \server\pentaho-server\pentaho-solutions\system\common-ui\resources\themes\<theme-name> directory and open the .css file with a text editor.

    3. Locate the #login-background property, then adjust the dimensions, position, and other properties for the background image.

  6. Save and close the file.

  7. Clear the web browser cache and restart the server to see the new logo.


The default theme logo is removed, and your custom logo appears in its place. If you replaced the background image, the new background also appears. You can also use the same process to modify or replace the remaining elements on the login page.

Add a logo to the web application

You can customize the Pentaho web application to display a logo. The best way to do this is to edit the Mantle.jsp file in the pentaho/server/pentaho-server/tomcat/webapps/pentaho/mantle/ folder.

In this example, the logo is added to the header on the right, but you can add it to the left or as a banner on the top or bottom of the page.

<div id="pucWrapper" cellspacing="0" cellpadding="0"  style="width: 100%; height: 100%;">
        <div id="pucHeader" cellspacing="0" cellpadding="0">
		<div id="logo" style="float: right; padding-right:10px"><IMG src="mantle/logo.png"></IMG></div>

The logo.png is used as the graphic within the pucHeader div.

Make custom User Console themes

The User Console's graphical interface is built on a CSS-based theme system. The sections below contain information for theme designers and developers.

Understanding theme system basics

The CSS-based theme system enables you to change the look of the Pentaho Server. With this type of theme system, you can create or add your own themes by working with just a few key configuration files.

The style sheets that make up the look and feel of the User Console, Dashboard Designer, Analyzer, and Interactive Reports are mostly in one location. These styles and scripts combine to make the default system theme, Ruby. This theme is located in the Common UI plug-in directory: pentaho/server/pentaho-server/pentaho-solutions/system/common-ui/resources/themes.

Themes can be systemwide or local.

  • Systemwide

    Common styles and scripts applied across the client tools of the entire Pentaho Server. For example, the style of the buttons used in the client tools are defined in the default systemwide Ruby theme. A modification to the buttons in the Ruby theme changes the way buttons look in all the client tools.

  • Local

    Styles and scripts applied to a particular area, also known as context. Contexts include Pentaho Server plug-ins as well as the names of the top-level directories in the Pentaho WAR file. These theme resources only take effect in their particular area of the Pentaho Server client tools.

Any page that includes the webcontext.js script automatically contains all of the active theme's JavaScript and CSS files when shown by the Pentaho Server.

For example, the following theme, called Crystal, contains one CSS and JavaScript file:

<themes root-folder="style">
   <crystal display-name="Crystal" system="true">

When this theme is active, the following resources are added to the HTML page:

<script type="text/javascript" src="/pentaho/common-ui/themes/crystal/crystalStyles.js"></script>
<link rel="stylesheet" type="text/css" href="/pentaho/common-ui/themes/crystal/crystalStyles.css"/>

This automatic insertion of theme resources makes it possible to change themes without having to edit the main content HTML documents to include the theme resource's tag individually. The theme system can include any number of JavaScript and CSS files defined for your theme.

Although resources are automatically inserted, your CSS changes will not appear in the User Console until you start and restart the Pentaho Server. Every time you modify a theme along with any XML or CSS files, the Pentaho Server must be restarted before your changes can appear in the User Console.

You can add local styles in a similar fashion. The only requirement is for you to tell the system what context you need to load. You can tell the system what needs to be loaded by adding ?context=myPlugin to the webcontext.js script where myPlugin is the name of your plug-in or root WAR folder:

<script type="text/javascript" src="webContext.js?context=myPlugin"></script>

Creating a new theme

The best way to create a new theme is to copy an existing theme folder structure and modify it to make it your own. Make sure to duplicate the theme folder structure in both the pentaho/server/pentaho-server/pentaho-solutions/system/common-ui and pentaho/server/pentaho-server/tomcat/webapps/pentaho/mantle/themes directories when copying an existing theme.

On startup, the Pentaho Server searches for themes.xml files in every plug-in and root-level folder in the Pentaho WAR file. Multiple themes can be defined in the themes.xml files of each directory. Themes can be systemwide, local, or a combination of both. The following example defines both a systemwide and local theme named Crystal.

<themes root-folder="resources/themes">
    <crystal display-name="Crystal" system="true">
    <crystal display-name="Crystal" system="true">

The <themes> node has a root-folder attribute. The value of this attribute is the name of the directory (relative to the Web application context) where your themes are stored. For WAR-based contexts, it is simply a directory name inside the WAR file. For example, if your theme is located under an accounting folder inside the structure of your Pentaho WAR file, the resources are loaded from the accounting/resources/themes folder of this structure.

Besides inserting the new <themes> node into the themes.xml files, you need to change the name of the mantleTheme_name.css file in the copied mantle theme folder structure to match your new theme name (Theme_name). After changing this file name, re-edit the themes.xml file in pentaho/server/biserveree/tomcat/webapps/pentaho/mantle to include a reference to this new CSS file.

Plug-in resource loading is different than WAR-based loading. With this type of loading, the plug-in controls how resources are mapped to the URL. If the theme file from above was located in a plug-in called accounting, then the resources are accessed from the following URL: pentaho/context/accounting/resources/themes/. This kind of resource mapping is most commonly implemented in Pentaho Server plug-ins through static-path entries:

    <static-path url="/accounting/resources" localFolder="resources"/>

When you want your changes to appear, restart the Pentaho Server before opening the User Console.

Setting the default theme

The default system theme is defined in the pentaho-solutions/system/pentaho.xml configuration file through the <default-theme> node. The Pentaho Server ships with Ruby as the default theme; changing the value to another theme name will set the default active theme for all User Console users.

Switching console themes

If you have created an alternate theme or localized message bundle, you can switch to it through the View menu in the Pentaho User Console.

NoteYou can prevent themes from appearing in this menu by adding a hidden="true" property to the theme node.

You can manually specify a theme for a specified page by including a theme= URL parameter. Only the requested page is affected. For example, the following URL loads the Sapphire theme systemwide and local themes if available:


If either the systemwide or local debug theme is not found, the resources for the currently active theme are loaded instead, which is useful when testing new themes and for loading debug versions of scripts and styles.

It is also possible to set the session variable pentaho-user-theme to the desired theme name, which is usually done in a start-up action to have per-user themes in multi-tenancy scenarios.

Test your CSS changes

The style sheet files explained earlier in this section contain many style definitions, which makes it difficult to map the CSS classes to what you see in the application at runtime. To make this task easier, we recommend that you use the DevTools for Chrome, Web Inspector for Safari, or Firebug for Firefox to inspect the UI elements you want to style.

Once you have selected an element, you can view all of the CSS properties that apply to it, then change the CSS and watch your changes take immediate effect. This allows you to quickly and easily find the appropriate CSS to edit and gives you the ability to preview your changes in real time.

Localize the Pentaho Server

You can localize the Pentaho User Console, Pentaho Analyzer, and Dashboard Designer by creating locale- and language-specific message bundles within the Pentaho web application. Message bundles are dynamically adjusted according to browser locale, so you can create localized message bundles for every language you want to support, and let each individual user's system language settings determine which one is loaded.

Stop the Pentaho Server before editing anything inside of the Pentaho WAR file.

For brevity's sake, only the default Pentaho User Console files will be explained in detail. The file naming convention is identical among all message bundles in Pentaho Business Analytics. The following files are located in the mantle/messages/ directory:


    The default message bundle for the Pentaho User Console. In its initial condition, it is a copy of If you want to change the default language and dialect, copy your preferred message bundle file over this one.


    The English-language version of the standard message bundle. This is an identical copy of


    The French-language version of the standard message bundle.


    The German-language version of the standard message bundle.


    Contains a list of localized message bundles and the native language names they correspond to; this relieves the Pentaho Server of the burden of having to discover them on its own. A file should be created for every message bundle that you intend to localize.

The following code is an example of the content found in the file:


New files are created in the following format: where xx represents a lowercase two-letter language code, and YY represents a two-letter locale code, where applicable. So, for instance, U.S. and British English could have two separate message bundles if you wanted to draw a distinction between the two dialects:


The language and country codes must be in standard ISO format. You can look up both sets of codes on these pages:

You can edit the default message bundle directly if you need to make surgical changes to the content inside of it. If you plan to translate it into another language, it makes more sense to copy the file and change the name appropriately, then translate it line by line. Be sure to update with the new country and dialect code and the native language name that it corresponds to.

NoteAll message bundles must be UTF-8 encoded.