JBoss.org Community Documentation

- Prev
- Next

## Chapter 10. Themes

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.

## 10.1. Theme types

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

## 10.2. Configure theme

All theme types, except welcome, is configured through `Keycloak Admin Console`. To change the theme used for a realm 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"
    }

## 10.3. Default themes

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.

## 10.4. Creating a theme

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.

### 10.4.1. Stylesheets

A theme can have one or more stylesheets, to add a stylesheet create a file inside `resources/css` (for example `resources/css/styles.css`) inside your theme folder. Then registering it in `theme.properties` by adding:

    styles=css/styles.css

The `styles` property supports a space separated list so you can add as many as you want. For example:

    styles=css/styles.css css/more-styles.css

### 10.4.2. Scripts

A theme can have one or more scripts, to add a script create a file inside `resources/js` (for example `resources/js/script.js`) inside your theme folder. Then registering it in `theme.properties` by adding:

    scripts=js/script.js

The `scripts` property supports a space separated list so you can add as many as you want. For example:

    scripts=js/script.js js/more-script.js

### 10.4.3. Images

To make images available to the theme add them to `resources/img`. They can then be used through stylesheets. For example:

    body {
        background-image: url('../img/image.jpg');
    }

Or in templates, for example:

    <img src="${url.resourcesPath}/img/image.jpg">

### 10.4.4. Messages

Text in the templates are loaded from message bundles. Currently internationalization isn't supported, but that will be added in a later release. A theme that extends another theme will inherit all messages from the parents message bundle, but can override individual messages. For example to replace `Username` on the login form with `Your Username` create the file `messages/messages.properties` inside your theme folder and add the following content:

    username=Your Username

### 10.4.5. Modifying HTML

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.

## 10.5. SPIs

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

### 10.5.1. Theme SPI

The Theme SPI allows creating different mechanisms to load themes for the default FreeMarker based implementations of login forms and account management. To create a theme provider you will need to implement `org.keycloak.freemarker.ThemeProviderFactory` and `org.keycloak.freemarker.ThemeProvider`.

Keycloak comes with two theme providers, one that loads themes from the classpath (used by default themes) and another that loads themes from a folder (used by custom themes). Looking at these would be a good place to start to create your own theme provider. You can find them inside `forms/common-themes` on GitHub or the source download.

### 10.5.2. Account SPI

The Account SPI allows implementing the account management pages using whatever web framework or templating engine you want. To create an Account provider implement `org.keycloak.account.AccountProviderFactory` and `org.keycloak.account.AccountProvider`.

Once you have deployed your account provider to Keycloak you need to configure `keycloak-server.json` to specify which provider should be used:

    "account": {
        "provider": "custom-provider"
    }

### 10.5.3. Login SPI

The Login SPI allows implementing the login forms using whatever web framework or templating engine you want. To create a Login forms provider implement `org.keycloak.login.LoginFormsProviderFactory` and `org.keycloak.login.LoginFormsProvider` in `forms/login-api`.

Once you have deployed your account provider to Keycloak you need to configure `keycloak-server.json` to specify which provider should be used:

    "login": {
        "provider": "custom-provider"
    }

- PrevChapter 9. Social
- Top of page
- Front page
- NextChapter 11. Email