Mega Menu
  • JavaServer Faces
    • PrimeFaces

      UI Components for JSF
    • Premium Templates

      UI Components for JSF
    • Extensions

      UI Components for JSF
  • Angular
    • PrimeNG

      UI Components for Angular
    • Premium Templates

      UI Components for Angular
  • React
    • PrimeReact

      UI Components for React
    • Premium Templates

      UI Components for React
    • Calendar

    • Messages

      Today, you have new 4 messages
    • Deals

  • Olivia Eklund

    Design
    • Weekly Performance

      Olivia Eklund

      Design
  • Olivia Eklund

    Design
    • Weekly Performance

      Olivia Eklund

      Design
Today

Wednesday, 26 Jun

Tasks

You have 2 tasks today
  • Sales Report

    Today
  • Pay Invoices

    Today
  • Customer Meeting

    Later
  • Expense Reports

    Later
  • Plane Tickets

    Later
  • Dinner with Tony

    Later

Calendar

Weather

  • 15.03

    Lille

    31°
  • 15.03

    Barcelona

    26°
  • 09.03

    New York

    23°
  • 15.03

    Amsterdam

    31°
  • 09.03

    Antalya

    33°
👋 Bonjour Olivia, there is no notification today for you

Getting Started

To begin with, you'd need SASS to compile CSS, proceed to SASS Installation before beginning if you do not have SASS available in your command line.

Demo project has an integrated jetty plugin so running the sample is easy as building the css first followed by the mvn jetty:run command.

sass --update src/main/webapp/resources/ --sourcemap=none
mvn jetty:run

Navigate to http://localhost:8080/mirage to view the demos which is exactly same as the live version.

Template

Mirage utilizes JSF templating APIs and provides a main template.xhtml along with additional topbar, sidebar, rightpanel, breadcrumb and footer fragments for the base layout. These xhtml files must be placed under WEB-INF folder and client pages should reference the template.xhtml as their template. Provided empty.xhtml is a sample content page using the main template.xhtml that defines "content" as the main ui:define placeholder. By default template defines 3 placeholders (page title, header content and actual content) to insert content and you can add more as per your requirements.

Sample page below uses the main template from Mirage.

<ui:composition xmlns="http://www.w3.org/1999/xhtml"
                xmlns:h="http://java.sun.com/jsf/html"
                xmlns:f="http://java.sun.com/jsf/core"
                xmlns:ui="http://java.sun.com/jsf/facelets"
                xmlns:p="http://primefaces.org/ui"
                template="/WEB-INF/template.xhtml">

    <ui:define name="title">Test Page</ui:define>

    <ui:define name="content">
        Content goes here
    </ui:define>

</ui:composition>

Other required resources are the css, js and images that are located inside resources/mirage-layout folder, simply copy the mirage-layout folder to your %WEB-APP-FOLDER%/resources folder so that final path would be %WEB-APP-FOLDER%/resources/mirage-layout/. Please refer to demo app or maven project of the demo app as the reference.

GuestPreferences Bean

GuestPreferences is a simple session scoped bean to keep the user customizations of the layout, template xhtml files refer to this bean to dynamically change their behavior such as menu mode or theme. This bean is not necessary to run the Mirage and only used for demo purposes. For example template.xhtml includes layout color depending on a user preference using an EL expression.

<h:outputStylesheet name="css/layout-#{guestPreferences.layout}.css" library="mirage-layout" />

In your application, you may also need a similar bean to make the template dynamic or choose a static color with;

<h:outputStylesheet name="css/layout-blue.css" library="mirage-layout" />

Component Theme

Mirage provides 24 PrimeFaces themes out of the box featuring light and dark alternatives. Setup of a theme simple as including the theme jar in your classpath and defining primefaces.THEME context parameter in web.xml such as "primefaces-mirage-blue-light". Full list of available themes are;

  • primefaces-mirage-blue-light
  • primefaces-mirage-blue-dark
  • primefaces-mirage-brown-light
  • primefaces-mirage-brown-dark
  • primefaces-mirage-cyan-light
  • primefaces-mirage-cyan-dark
  • primefaces-mirage-green-light
  • primefaces-mirage-green-dark
  • primefaces-mirage-indigo-light
  • primefaces-mirage-indigo-dark
  • primefaces-mirage-lime-light
  • primefaces-mirage-lime-dark
  • primefaces-mirage-magenta-light
  • primefaces-mirage-magenta-dark
  • primefaces-mirage-orange-light
  • primefaces-mirage-orange-dark
  • primefaces-mirage-purple-light
  • primefaces-mirage-purple-dark
  • primefaces-mirage-red-light
  • primefaces-mirage-red-dark
  • primefaces-mirage-teal-light
  • primefaces-mirage-teal-dark
  • primefaces-mirage-yellow-light
  • primefaces-mirage-yellow-dark

A custom theme can be developed by the following steps.

  • Create a custom theme folder such as primefaces-mirage-myown under webapp/resources and place an empty theme.scss inside.
  • Copy the sass folder from the distribution to webapp/resources.
  • Define the variables listed below and import the /sass/theme/_theme.scss file.
  • Build the scss to generate css.
  • Set primefaces.THEME context parameter as mirage-myown
  • Either bundle the css in a jar file or serve from webapp/resources/primefaces-mirage-myown folder

Here are the variables required to create a theme based on a light color scheme.

//main
$primaryColor:#5E81AC;
$primaryTextColor:#ffffff;

//highlight
$highlightBgColor:$primaryColor;
$highlightTextColor:$primaryTextColor;

//input
$inputFocusBorderColor:#9EB3CD;
$inputFocusBorderShadowColor:rgba(22,107,212,.25);

//primary button
$primaryButtonTextColor:#ffffff;
$primaryButtonBgColor:#5E81AC;
$primaryButtonBorderColor:#5E81AC;
$primaryButtonHoverBgColor:#466489;
$primaryButtonHoverBorderColor:#466489;
$primaryButtonActiveBgColor:#263951;
$primaryButtonActiveBorderColor:#263951;
$primaryButtonFocusBorderShadow:rgba(22,107,212,.5);

@import '../sass/variables/_theme_light';
@import '../sass/theme/_theme';

Dark alternative needs to import the _theme_dark file instead.

//main
$primaryColor:#5E81AC;
$primaryTextColor:#ffffff;

//highlight
$highlightBgColor:$primaryColor;
$highlightTextColor:$primaryTextColor;

//input
$inputFocusBorderColor:#9EB3CD;
$inputFocusBorderShadowColor:rgba(22,107,212,.25);

//primary button
$primaryButtonTextColor:#ffffff;
$primaryButtonBgColor:#5E81AC;
$primaryButtonBorderColor:#5E81AC;
$primaryButtonHoverBgColor:#466489;
$primaryButtonHoverBorderColor:#466489;
$primaryButtonActiveBgColor:#263951;
$primaryButtonActiveBorderColor:#263951;
$primaryButtonFocusBorderShadow:rgba(22,107,212,.5);

@import '../sass/variables/_theme_dark';
@import '../sass/theme/_theme';

An example sass command to compile the css would be;

sass src/main/webapp/resources/primefaces-mirage-myown/theme.scss src/main/webapp/resources/primefaces-mirage-myown/theme.css  --sourcemap=none

Watch mode is handy to avoid compiling everytime when a change is made, instead use the following command so that sass generates the file whenever you make a customization. This builds all css files whenever a change is made to any scss file.

sass -w src/main/webapp/resources/ --sourcemap=none

Layout Theme

There are 24 layout colors in total with light and dark alternatives. The primary colors Configuring a layout color is easy as adding the css file to the template.xhtml where the choice can be left to the user with an EL expression.

<h:outputStylesheet name="css/layout-#{guestPreferences.layout}.css" library="mirage-layout" />

Full list of available layout themes are.

  • layout-blue-light
  • layout-blue-dark
  • layout-brown-light
  • layout-brown-dark
  • layout-cyan-light
  • layout-cyan-dark
  • layout-green-light
  • layout-green-dark
  • layout-indigo-light
  • layout-indigo-dark
  • layout-lime-light
  • layout-lime-dark
  • layout-magenta-light
  • layout-magenta-dark
  • layout-orange-light
  • layout-orange-dark
  • layout-purple-light
  • layout-purple-dark
  • layout-red-light
  • layout-red-dark
  • layout-teal-light
  • layout-teal-dark
  • layout-yellow-light
  • layout-yellow-dark

Creating a custom layout with the color scheme of your choice is similar to creating a custom theme.

  • Choose a layout name such as layout-myown.
  • Create an empty file named layout-myown.scss inside resources/mirage-layout/css folder.
  • Copy the sass folder from the distribution to webapp/resources.
  • Define the variables listed below and import the /sass/layout/_layout.scss file.
  • Build the scss to generate css
  • Serve the css by importing it using a link tag or h:outputStylesheet.

Here are the variables required to create a layout.

$primaryColor:#5e81ac;
$primaryLightColor:#809bbd;
$primaryTextColor:#ffffff;

@import '../../sass/variables/_layout_light';
@import '../../sass/layout/_layout';

Dark alternative needs to import the _theme_dark file instead.

$primaryColor:#5e81ac;
$primaryLightColor:#809bbd;
$primaryTextColor:#ffffff;

@import '../../sass/variables/_layout_dark';
@import '../../sass/layout/_layout';

SASS Variables

In case you'd like to customize common variables, the _common.scss under sass variables folder is where the core variables (e.g. font size, paddings) for the layout are defined.

//general
$fontSize:14px;
$fontFamily:-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
$transitionDuration:.15s;
$letterSpacing:normal;
$borderRadius:4px;
$mobileBreakpoint:991px;

_layout.scss under variables define the shared variables of the layout.

@import './common';

_layout_light.scss contains the shared variables of the layout themes with a light color scheme.

$bodyBgColor:#eceff4;
$textColor:#4c566a;
$textSecondaryColor:#9199a9;

$topbarBgColor:#eceff4;
$breadcrumbBgColor:#d8dee9;
$contentBgColor:#ffffff;
$contentAltBgColor:#f9fafb;
$contentAltBorderColor:#e5e9f0;
$dividerColor:rgba(145,153,169,0.3);
$menuShadow:3px 0 5px 0 rgba(33, 35, 39, 0.15);

@import './_layout';

_layout_dark.scss contains the shared variables of the layout themes with a light color scheme.

$bodyBgColor:#2e3440;
$textColor:#d8dee9;
$textSecondaryColor:#9199a9;

$topbarBgColor:#2e3440;
$breadcrumbBgColor:#20252e;
$contentBgColor:#20252e;
$contentAltBgColor:#2e3440;
$contentAltBorderColor:#434c5e;
$dividerColor:rgba(90,101,124,0.3);
$menuShadow:3px 0 5px 0 rgba(33, 35, 39, 0.3);;

@import './_layout';

Shared variables of the components themes are available inside the _theme.scss file.

@import './common';

/* panels */
$headerPadding:10px 15px;
$contentPadding:15px;
$contentLineHeight:1.43;

/* forms */
$inputPadding:6px 12px;
$inputGroupAddonMinWidth:2*$fontSize;
$checkboxWidth:20px;
$checkboxHeight:20px;

/* list items */
$listPadding:6px 0;
$listItemPadding:8px 20px;

/* datatable */
$datatableCellPadding:.75em;

/* buttons */
$roundedButtonBorderRadius:15px;

$secondaryButtonTextColor:#ffffff;
$secondaryButtonBgColor:#6c757d;
$secondaryButtonBorderColor:#6c757d;
$secondaryButtonHoverBgColor:#5a6268;
$secondaryButtonHoverBorderColor:#545b62;
$secondaryButtonActiveBgColor:#545b62;
$secondaryButtonActiveBorderColor:#4e555b;
$secondaryButtonFocusBorderShadow:rgba(130,138,145,.5);

$successButtonTextColor:#ffffff;
$successButtonBgColor:#99CE6B;
$successButtonBorderColor:#99CE6B;
$successButtonHoverBgColor:#75A24D;
$successButtonHoverBorderColor:#75A24D;
$successButtonActiveBgColor:#4F7131;
$successButtonActiveBorderColor:#4F7131;
$successButtonFocusBorderShadow:rgba(72,180,97,.5);

$infoButtonTextColor:#ffffff;
$infoButtonBgColor:#88C0D0;
$infoButtonBorderColor:#88C0D0;
$infoButtonHoverBgColor:#6CA2B1;
$infoButtonHoverBorderColor:#6CA2B1;
$infoButtonActiveBgColor:#467481;
$infoButtonActiveBorderColor:#467481;
$infoButtonFocusBorderShadow:rgba(58,176,195,.5);

$warningButtonTextColor:#ffffff;
$warningButtonBgColor:#EBCB8B;
$warningButtonBorderColor:#EBCB8B;
$warningButtonHoverBgColor:#D2A956;
$warningButtonHoverBorderColor:#D2A956;
$warningButtonActiveBgColor:#A37518;
$warningButtonActiveBorderColor:#A37518;
$warningButtonFocusBorderShadow:rgba(222,170,12,.5);

$dangerButtonTextColor:#ffffff;
$dangerButtonBgColor:#F28686;
$dangerButtonBorderColor:#F28686;
$dangerButtonHoverBgColor:#D36161;
$dangerButtonHoverBorderColor:#D36161;
$dangerButtonActiveBgColor:#943F3F;
$dangerButtonActiveBorderColor:#943F3F;
$dangerButtonFocusBorderShadow:rgba(225,83,97,.5);

$darkButtonTextColor:#ffffff;
$darkButtonBgColor:#343a40;
$darkButtonBorderColor:#343a40;
$darkButtonHoverBgColor:#23272b;
$darkButtonHoverBorderColor:#1d2124;
$darkButtonActiveBgColor:#1d2124;
$darkButtonActiveBorderColor:#171a1d;
$darkButtonFocusBorderShadow:rgba(82,88,93,.5);

$lightButtonTextColor:#212529;
$lightButtonBgColor:#f8f9fa;
$lightButtonBorderColor:#f8f9fa;
$lightButtonHoverBgColor:#e2e6ea;
$lightButtonHoverBorderColor:#dae0e5;
$lightButtonActiveBgColor:#dae0e5;
$lightButtonActiveBorderColor:#d3d9df;
$lightButtonFocusBorderShadow:rgba(216,217,219,.5);

/* Messages */
$infoMessageBgColor:#D9EAF0;
$infoMessageBorderColor:#C3DFE7;
$infoMessageTextColor:#467481;
$warnMessageBgColor:#F8EED9;
$warnMessageBorderColor:#F5E5C5;
$warnMessageTextColor:#A37518;
$errorMessageBgColor:#FCE1E1;
$errorMessageBorderColor:#F8C2C2;
$errorMessageTextColor:#943F3F;
$fatalMessageBgColor:#999999;
$fatalMessageBorderColor:#797979;
$fatalMessageTextColor:#ffffff;

/* rating */
$ratingStarColor:#f790c8;

/* keyboard */
$keyboardShiftColor:#3e9018;
$keyboardBackColor:#007bff;
$keyboardClearColor:#f790c8;
$keyboardCloseColor:#9189fd;

/* modal */
$modalBgColor:#000000;
$modalBgOpacity:.5;

_theme_light.scss contains the shared variables of the component themes with a light color scheme.

@import '../variables/_theme';

/* Common */
$textColor:#4c566a;
$textSecondaryColor:#9199a9;
$disabledBgColor:#eeeeee;
$dividerColor:rgba(145,153,169,0.3);

/* Icons */
$iconFontSize:14px;
$iconWidth:16px;

/* Error */
$errorColor:#a94442;

/* Headers */
$headerBgColor:#f5f5f5;
$headerHoverBgColor:#dcdcdc;
$headerHoverBorderColor:#c4c4c4;
$headerTextColor:#292B2C;
$headerBorderColor:#dddddd;
$headerIconColor:#999999;
$headerIconHoverColor:#bd9090;

/* Contents */
$contentBorderColor:#dddddd;
$contentBgColor:#ffffff;

/* Forms */
$inputBgColor:#ffffff;
$inputBorderColor:#cccccc;
$inputHoverBorderColor:#cccccc;
$inputTextColor:#495057;

//groups
$inputGroupBorderColor:#cccccc;
$inputGroupBgColor:#e9ecef;
$inputGroupTextColor:$textColor;
$inputGroupIconColor:$textSecondaryColor;

/* Buttons */
$toggleButtonBgColor:#eceff4;
$toggleButtonBorderColor:#e5e9f0;
$toggleButtonHoverBgColor:#e5e9f0;
$toggleButtonHoverBorderColor:#d8dee9;

/* List Items */
$listItemHoverBgColor:#f7f7f9;
$listItemHoverTextColor:#1d1e1f;

/* Overlays */
$overlayBorderColor:#cccccc;

/* Data */
$datatableCellBorderColor:#dddddd;
$datableEvenRowBgColor:rgba(0,0,0,.05);
$datatableHoverBgColor:rgba(0,0,0,.075);    

_theme_dark.scss contains the shared variables of the component themes with a light color scheme.

@import '../variables/_theme';

/* Common */
$textColor:#d8dee9;
$textSecondaryColor:#9199a9;
$disabledBgColor:#2e3440;
$dividerColor:rgba(90,101,124,0.3);

/* Icons */
$iconFontSize:14px;
$iconWidth:16px;

/* Error */
$errorColor:#a94442;

/* Headers */
$headerBgColor:#2e3440;
$headerHoverBgColor:#3b4252;
$headerHoverBorderColor:#434c5e;
$headerTextColor:#d8dee9;
$headerBorderColor:#434c5e;
$headerIconColor:#d8dee9;
$headerIconHoverColor:#d8dee9;

/* Contents */
$contentBorderColor:#434c5e;
$contentBgColor:#20252e;

/* Forms */
$inputBgColor:#20252e;
$inputBorderColor:#5a657c;
$inputHoverBorderColor:#5a657c;
$inputTextColor:#d8dee9;

//groups
$inputGroupBorderColor:#5a657c;
$inputGroupBgColor:#2e3440;
$inputGroupTextColor:$textColor;
$inputGroupIconColor:$textSecondaryColor;

/* Buttons */
$toggleButtonBgColor:#5a657c;
$toggleButtonBorderColor:#4c566a;
$toggleButtonHoverBgColor:#4c566a;
$toggleButtonHoverBorderColor:#434c5e;

/* List Items */
$listItemHoverBgColor:#4c566a;
$listItemHoverTextColor:#d8dee9;

/* Overlays */
$overlayBorderColor:#434c5e;

/* Data */
$datableEvenRowBgColor:#2e3440;
$datatableHoverBgColor:#4c566a;
$datatableCellBorderColor:#434c5e;

Menu

Menu is a regular JSF component that supports PrimeFaces MenuModel API allowing both declarative and programmatic approaches.

xmlns:pm="http://primefaces.org/mirage"

<pm:menu>
</pm:menu>

Menu has 3 modes; overlay and horizontal. Layout wrapper element in template.xhtml is used to define which mode to use by adding specific classes. Default is overlay and adding "layout-horizontal" enables horizontal mode.

  • Overlay (Default): "layout-wrapper"
  • Horizontal: "layout-wrapper layout-horizontal"

Layout mode can be dynamic using an EL expression as well using an example bean called userPreferences.

<div class="layout-wrapper #{guestPreferences.horizontalMenu ? 'layout-horizontal' ? ''}">
...
</div>

Menu Themes

Menu theme is defined at the main container element, template below uses the default light menus. Full list of menu themes are the following, note that layout-menu- prefix needs to be added to apply the style such as layout-menu-dark.

<div class="layout-wrapper layout-menu-dark">
...
</div>

Light and Dark menus utilize the primary color of the chosen layout whereas custom menu themes listed below define their own style. Apply the following style classes for a custom menu theme.

  • layout-menu-chile
  • layout-menu-naples
  • layout-menu-georgia
  • layout-menu-infinity
  • layout-menu-chicago
  • layout-menu-majesty
  • layout-menu-fish
  • layout-menu-dawn
  • layout-menu-record
  • layout-menu-pool
  • layout-menu-metal
  • layout-menu-china
  • layout-menu-table
  • layout-menu-panorama
  • layout-menu-barcelona
  • layout-menu-underwater
  • layout-menu-symmetry
  • layout-menu-rain
  • layout-menu-utah
  • layout-menu-wave
  • layout-menu-flora
  • layout-menu-speed
  • layout-menu-canopy
  • layout-menu-sanpaolo
  • layout-menu-basketball
  • layout-menu-misty
  • layout-menu-summit
  • layout-menu-snow
  • layout-menu-wall
  • layout-menu-ferris
  • layout-menu-ship
  • layout-menu-ny
  • layout-menu-cyan
  • layout-menu-violet
  • layout-menu-red
  • layout-menu-blue
  • layout-menu-porsuk
  • layout-menu-pink
  • layout-menu-purple
  • layout-menu-orange
<div class="layout-wrapper layout-menu-chile">
...
</div>

Creating a custom menu theme with the color scheme of your choice required the following steps.

  • Choose a menu theme such as myown.
  • Create an empty file named myown.scss inside resources/sass/layout/menu/themes/ folder.
  • Define the variables listed below and import the /sass/layout/_layout.scss file.
  • Import _menu_theme.scss file.
  • Import your file at resources/sass/layout/menu/_menu file.
  • .

Here are the variables required to create a layout.

.layout-menu-violet {
    $menuBgColor:#4A4358;
    $rootMenuitemTextColor:#ffffff;
    $rootMenuitemIconColor:#ffffff;
    $rootMenuitemHoverBgColor:rgba(255, 255, 255, 0.24);
    $activeRootMenuitemBgColor:#F8C869;
    $activeRootMenuitemTextColor:#343a40;
    $activeRootMenuitemIconColor:#343a40;
    $submenuBgColor:rgba(255, 255, 255, 0.12);
    $horizontalSubmenuBgColor:#2e3440;
    $submenuItemTextColor:#ffffff;
    $submenuItemIconColor:#ffffff;
    $submenuItemHoverBgColor:rgba(0, 0, 0, 0.36);
    $activeSubmenuItemTextColor:#F8C869;
    $activeSubmenuItemIconColor:#F8C869;
    $appNameTextColor:#ffffff;
    $pinBgColor:#ffffff;
    $pinIconColor:#2e3440;

    @import '../_menu_theme';
}

An image can be used as the background of the menu using the menuBgImage variable.

    .layout-menu-ferris {
        $menuBgColor: #262B33;
        $menuBgImage:'ferris.jpg';
        $horizontalMenuBgImage:'ferris-horizontal.jpg';
        $rootMenuitemTextColor:#eceff4;
        $rootMenuitemIconColor:#eceff4;
        $rootMenuitemHoverBgColor:rgba(255, 255, 255, 0.24);
        $activeRootMenuitemBgColor:#A3BE8C;
        $activeRootMenuitemTextColor:#3b4252;
        $activeRootMenuitemIconColor:#2e3440;
        $submenuBgColor:rgba(255, 255, 255, 0.12);
        $horizontalSubmenuBgColor:#2e3440;
        $submenuItemTextColor:#eceff4;
        $submenuItemIconColor:#eceff4;
        $submenuItemHoverBgColor:rgba(0, 0, 0, 0.32);
        $activeSubmenuItemTextColor:#A3BE8C;
        $activeSubmenuItemIconColor:#A3BE8C;
        $appNameTextColor:#ffffff;
        $pinBgColor:#ffffff;
        $pinIconColor:#2e3440;
    
        @import '../_menu_theme';
    }

Grid CSS

Mirage uses new PrimeFlex CSS throughout the demos however you may also use other Grid Utilities of your choice as well as Mirage layout does not depend on a specific grid library.

Tips

  • Familiarity with SASS is required to make customizations to the layout and theme.
  • Demo application war and the maven project tag are included in distribution however you don't necessarily need them to install Mirage, the actual artifacts required are the layout zip file and the theme jar.
  • Sample demo application war includes the JSF libraries so it is suggested to remove them from the war file when you deploy to an appserver.
  • When running the maven project, you need to build the sass with (sass --update src/main/webapp/resources/ --sourcemap=none) command.

Migration Guide

For seamless updates use the /sass/overrides/_layout_styles.scss, /sass/overrides/_layout_variables.scss for overriding the layout styles and /sass/overrides/_theme_styles.scss, /sass/overrides/_theme_variables.scss for customizing the theme styles instead of changing the scss files under layout and theme files to avoid maintenance issues. Updates usually require updating the layout and theme folders so your changes won't get effected during updates since they are kept in external files.

1.0.0 to 1.0.1

  • Update layout and theme css files.

Light or Dark

Mirage offers all dark dashboard & theme design for dark lovers.