NOTE: To set the theme for the `master` admin console you need to set the admin console theme for the `master` realm. To see the changes to the admin console
Unless you plan to replace every single page you should extend another theme. Most likely you will want to extend the {project_name} theme, but you could also
consider extending the base theme if you are significantly changing the look and feel of the pages. The base theme primarily consists of HTML templates and
When extending a theme you can override individual resources (templates, stylesheets, etc.). If you decide to override HTML templates bear in mind that you may
need to update your custom template when upgrading to a new release.
While creating a theme it's a good idea to disable caching as this makes it possible to edit theme resources directly from the `themes` directory without
To create a new theme start by creating a new directory in the `themes` directory. The name of the directory becomes the name of the theme. For example to
create a theme called `mytheme` create the directory `themes/mytheme`.
For each type create a file `theme.properties` which allows setting some configuration for the theme. For example to configure the theme `themes/mytheme/login`
that we just created to extend the base theme and import some common resources create the file `themes/mytheme/login/theme.properties` with following contents:
There are a list of properties that can be used to change the css class used for certain element types. For a list of these properties look at the theme.properties
file in the corresponding type of the keycloak theme (`themes/keycloak/<THEME TYPE>/theme.properties`).
When doing so, you can substitute system properties or environment variables by using these formats:
* `${some.system.property}` - for system properties
* `${env.ENV_VAR}` - for environment variables.
A default value can also be provided in case the system property or the environment variable is not found with `${foo:defaultValue}`.
NOTE: If no default value is provided and there's no corresponding system property or environment variable, then nothing is replaced and you end up with the format in your template.
Here's an example of what is possible:
[source,properties]
----
javaVersion=${java.version}
unixHome=${env.HOME:Unix home not found}
windowsHome=${env.HOMEPATH:Windows home not found}
A theme can have one or more stylesheets. To add a stylesheet create a file in the `<THEME TYPE>/resources/css` directory of your theme. Then add it to the `styles`
To see the changes open the login page for your realm. You will notice that the only styles being applied are those from your custom stylesheet. To include the
styles from the parent theme you need to load the styles from that theme as well. Do this by editing `themes/mytheme/login/theme.properties` and changing `styles`
A theme can have one or more scripts, to add a script create a file in the `<THEME TYPE>/resources/js` directory of your theme. Then add it to the `scripts`
property in `theme.properties`.
For example to add `script.js` to the `mytheme` create `themes/mytheme/login/resources/js/script.js` with the following content:
To make images available to the theme add them to the `<THEME TYPE>/resources/img` directory of your theme. These can be used from within stylesheets or
Text in the templates is loaded from message bundles. A theme that extends another theme will inherit all messages from the parent's message bundle and you can
Within a message values like `{0}` and `{1}` are replaced with arguments when the message is used. For example {0} in `Log in to {0}` is replaced with the name
To add a new language create the file `<THEME TYPE>/messages/messages_<LOCALE>.properties` in the directory of your theme. Then add it to the `locales` property in
`<THEME TYPE>/theme.properties`. For a language to be available to users the realms `login`, `account` and `email` theme has to support the language, so you
Finally you need to add a translation for the language selector. This is done by adding a message to the English translation. To do this add the following to
`themes/mytheme/account/messages/messages_en.properties` and `themes/mytheme/login/messages/messages_en.properties`:
By default message properties files should be encoded using ISO-8859-1. It's also possible to specify the encoding using a special header. For example to use UTF-8 encoding:
{project_name} supports adding icons for custom Identity providers, which are displayed on the login screen.
You just have to define an icon classes in your login `theme.properties` file (f.e. `themes/mytheme/login/theme.properties`) with key pattern `kcLogoIdP-<alias>`.
For Identity provider with alias `myProvider`, you may add line, like below, to login theme properties of your custom theme.
[source]
----
kcLogoIdP-myProvider = fa fa-lock
----
All icons are available on the official website of PatternFly4.
Icons for social providers are already defined in base login theme properties (`themes/keycloak/login/theme.properties`), where you can inspire yourself.
{project_name} uses https://freemarker.apache.org/[Freemarker Templates] in order to generate HTML. You can override individual templates in your own theme by
creating `<THEME TYPE>/<TEMPLATE>.ftl`. For a list of templates used see `themes/base/<THEME TYPE>`.
When creating a custom template it is a good idea to copy the template from the base theme to your own theme, then applying the modifications you need. Bear in
For example to create a custom login form for the `mytheme` theme copy `themes/base/login/login.ftl` to `themes/mytheme/login` and open it in an editor.
After the first line (<#import ...>) add `<h1>HELLO WORLD!</h1>` like so:
To edit the subject and contents for emails, for example password recovery email, add a message bundle to the `email` type of your theme. There are three messages for each email. One for the subject, one for the plain text body and one for the html body.
To see all emails available take a look at `themes/base/email/messages/messages_en.properties`.
For example to change the password recovery email for the `mytheme` theme create `themes/mytheme/email/messages/messages_en.properties` with the following
Themes can be deployed to {project_name} by copying the theme directory to `themes` or it can be deployed as an archive. During development you can copy the
theme to the `themes` directory, but in production you may want to consider using an `archive`. An `archive` makes it simpler to have a versioned copy of
To deploy a theme as an archive you need to create a JAR archive with the theme resources. You also need to add a file `META-INF/keycloak-themes.json` to the
