Skip to main content
Hitachi Vantara Lumada and Pentaho Documentation

Customize the Pentaho User Console

You can alter 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 alter interactive elements of Reporting, Analysis, and Dashboards. If you need to configure or manage Pentaho Server users and their roles, as opposed to changing its style, please use the Administration page of the console.

Before editing anything in the Pentaho WAR file, you must stop the web application server on which you are running the Pentaho Suite.

Location of Customizable Configuration Files


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 Name Location Description
globalCrystal.css /pentaho-solutions/system/common-ui/resources/themes/crystal/ This is the main structural, theme-specific style sheet for the default theme for the User Console (Crystal).
mantleCrystal.css tomcat/webapps/pentaho/mantle/themes/crystal/ This is the customizable presentation portion of the theme style sheet for the default theme for the User Console (Crystal).
globalOnyx.css /pentaho-solutions/system/common-ui/resources/themes/onyx/ This is the main structural, theme-specific style sheet for an alternate theme for the User Console (Onyx).
mantleOnyx.css tomcat/webapps/pentaho/mantle/themes/onyx/ This is the customizable presentation portion of the theme style sheet for an alternate theme for the User Console (Onyx).

Product-Specific Theme Settings for Analyzer, Dashboard Designer, and Interactive Reporting

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 Name Location Description
Analyzer /pentaho-solutions/system/analyzer/styles/themes/ Style sheets and theming materials for Analyzer.
Interactive Reporting /pentaho-solutions/system/pentaho-interactive-reporting/resources/web/themes/ Style sheets and theming materials for Interactive Reporting.
Dashboard Designer /pentaho-solutions/system/dashboards/resources/themes/ Style sheets and theming materials for Dashboard Designer.

Change the Background Image

You can change the background image that appears in the content pane in the Pentaho User Console by modifying or replacing the login-crystal-bg.jpeg file in the pentaho/system/common-ui/resources/themes/<theme-name>/images folder. The folder and file name must be identical.

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 Reporting 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 and/or localized message bundle, you can switch to it through the View menu in the Pentaho User Console.

You 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 particular 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 current active theme loads, which is particularly useful when testing out 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've 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.