Skip to content
Keycloak — From Zero to Hero

Themes

What are Keycloak themes?

Section titled “What are Keycloak themes?”

Keycloak renders several pages using its own HTML templates. Each page category is called a theme type:

Theme typeWhat it controls
loginThe login, registration, password-reset, and OTP pages
accountThe self-service account management console
emailEmail templates (verification, password reset, etc.)
adminThe Keycloak admin console itself

The login theme is the one your end-users see. Customising it to match your brand makes the authentication experience feel native to your product.

Setting a realm’s login theme

Section titled “Setting a realm’s login theme”

You can change the active login theme for any realm from the admin console:

  1. Open the admin console and select your realm from the top-left drop-down.
  2. Click Realm settings in the left sidebar.
  3. Click the Themes tab.
  4. Under Login theme, open the drop-down and choose your theme (e.g., keycloak for the default, or your custom theme name).
  5. Under Account theme, Email theme, and Admin console theme, choose accordingly.
  6. Click Save.

The change takes effect immediately — no restart required.

Structure of a custom theme

Section titled “Structure of a custom theme”

A custom theme is a directory you place under Keycloak’s themes/ folder. The minimal structure for a login theme looks like this:

flowchart TD
  T["themes/"] --> B["my-brand/"]
  B --> L["login/"]
  L --> P["theme.properties"]
  L --> R["resources/"]
  R --> CSS["css/login.css"]
  R --> IMG["img/logo.png"]
  L --> M["messages/messages_en.properties"]
A custom theme's directory structure

The theme.properties file declares which parent theme yours inherits from. Start by extending the built-in keycloak theme so you only need to override what you change:

parent=keycloak
import=common/keycloak

With this in place, Keycloak falls back to the parent for any template or resource you have not overridden.

Deploying a custom theme

Section titled “Deploying a custom theme”

For the Quarkus-based Keycloak distribution, copy your theme directory into the container’s /opt/keycloak/themes/ folder. The simplest approach with Docker is a bind-mount:

Terminal window
docker run -p 8080:8080 \
  -v "$(pwd)/themes/my-brand:/opt/keycloak/themes/my-brand" \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest \
  start-dev

After the container starts, your theme appears in the Login theme drop-down in Realm settings.

Keycloakify for React-based themes

Section titled “Keycloakify for React-based themes”

If you prefer to build your login pages with React, Keycloakify (keycloakify.dev) is the recommended tool. It compiles your React components into a Keycloak-compatible theme JAR. The output is a .jar file you drop into /opt/keycloak/providers/ — Keycloak auto-discovers it on startup.

Keycloakify gives you full React component control over every login page while staying compatible with Keycloak’s internal message-passing and form-submission protocol.

Which Keycloak theme type controls the login and registration pages?
Where in the admin console do you change a realm's active login theme?
What does the parent= line in theme.properties do?
What does Keycloakify do?