JBoss.org Community Documentation

- Prev
- Next

## Chapter 9. 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.

## 9.1. Configure theme

To configure the theme used by a realm open the `Keycloak Admin Console`, select your realm from the drop-down box in the top left corner. In the `Optional Settings` use the drop-down boxes for `Login Theme` and `Account Theme` to select the theme used by login forms and account management pages.

## 9.2. 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.

## 9.3. Creating a theme

There are several types of themes in Keycloak:

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

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.

### 9.3.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

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

### 9.3.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">

### 9.3.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

### 9.3.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.

## 9.4. SPIs

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

### 9.4.1. Theme SPI

The Theme SPI allows creating different mechanisms to providing 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.ThemeProvider` and `org.keycloak.freemarker.Theme` in `forms/common-freemarker`.

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.

### 9.4.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` in `forms/account-api`.

Keycloaks default account management provider is built on the FreeMarker template engine (`forms/account-freemarker`). To make sure your provider is loaded you will either need to delete `standalone/deployments/auth-server.war/WEB-INF/lib/keycloak-account-freemarker-1.0-beta-3.jar` or disable it with the system property `org.keycloak.account.freemarker.FreeMarkerAccountProviderFactory`.

### 9.4.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`.

Keycloaks default login forms provider is built on the FreeMarker template engine (`forms/login-freemarker`). To make sure your provider is loaded you will either need to delete `standalone/deployments/auth-server.war/WEB-INF/lib/keycloak-login-freemarker-1.0-beta-3.jar` or disable it with the system property `org.keycloak.login.freemarker.FreeMarkerLoginFormsProviderFactory`.

- PrevChapter 8. Social
- Top of page
- Front page
- NextChapter 10. Email