JBoss.orgCommunity Documentation

Chapter 9. Themes

9.1. Theme types
9.2. Configure theme
9.3. Default themes
9.4. Creating a theme
9.4.1. Stylesheets
9.4.2. Scripts
9.4.3. Images
9.4.4. Messages
9.4.5. Modifying HTML
9.5. SPIs
9.5.1. Theme SPI
9.5.2. Account SPI
9.5.3. Login SPI

Keycloak provides theme support for login forms and account management. This allows customizing the look and feel of end-user facing pages so they can be integrated with your brand and applications.

There are several types of themes in Keycloak:

  • Account - Account management
  • Admin - Admin console
  • Common - Shared resources for themes
  • Email - Emails
  • Login - Login forms
  • Welcome - Welcome pages

All theme types, except welcome, is configured through Keycloak Admin Console. To change the theme used for a realm open the open the Keycloak Admin Console, select your realm from the drop-down box in the top left corner. Under Settings click on Theme.

To change the welcome theme you need to edit standalone/configuration/keycloak-server.json and add welcomeTheme to the theme element, for example:

"theme": {
    ...
    "welcomeTheme": "custom-theme"
}

Keycloak comes bundled with default themes in standalone/configuration/themes. It is not recommended to edit these themes directly. Instead you should create a new theme to extend a default theme. A good reference is to copy the keycloak themes as these extend the base theme to add styling.

A theme consists of:

  • FreeMarker templates
  • Stylesheets
  • Scripts
  • Images
  • Message bundles
  • Theme properties

A theme can extend another theme. When extending a theme you can override individual files (templates, stylesheets, etc.). The recommended way to create a theme is to extend the base theme. The base theme provides templates and a default message bundle. It should be possible to achieve the customization required by styling these templates.

To create a new theme, create a folder in .../standalone/configuration/themes/<theme type>. The name of the folder is the name of the theme. Then create a file theme.properties inside the theme folder. The contents of the file should be:

parent=base

You have now created your theme. Check that it works by configuring it for a realm. It should look the same as the base theme as you've not added anything to it yet. The next sections will describe how to modify the theme.

Keycloak uses Freemarker Templates in order to generate HTML. These templates are defined in .ftl files and can be overriden from the base theme. Check out the Freemarker website on how to form a template file.

For full control of login forms and account management Keycloak provides a number of SPIs.