Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 37 ยท Customization

Themes and Custom Login Pages

Customize Keycloak with themes: theme types, folder layout, theme.properties inheritance, FreeMarker templates, message bundles, CSS, and deploying a custom login theme.

The login page is the one screen every user sees, so it should look like your product. Keycloak controls its look through themes. A theme is a folder of templates, styles, images, and text bundles. You rarely write a theme from scratch: you create a small theme that inherits from a built-in one and overrides only what you need, such as a logo, colors, and a few labels.

Keycloak does not run on this site, so nothing here can be previewed in place. The file layouts are real. The TryIt blocks are JavaScript stand-ins that model how Keycloak resolves files and messages through a theme chain.

Theme types

A theme can supply any of these types. Each is a subfolder, and each type is selected separately per realm:

Type What it styles
login Login, registration, password reset, required actions, consent
account The user-facing account console
admin The admin console
email Email templates and their text
welcome The initial welcome page

Select them under Realm settings > Themes: Login theme, Account theme, Admin console theme, and Email theme. Changes apply to the realm, and you can set a different theme per client in the client's Login settings (Login theme).

Folder layout

Custom themes live in the themes directory of the server (for example /opt/keycloak/themes). A minimal login theme looks like this:

TEXT
themes/
  acme/
    login/
      theme.properties
      messages/
        messages_en.properties
      resources/
        css/
          acme.css
        img/
          logo.svg

The theme.properties file is the heart of it:

PROPERTIES
parent=keycloak.v2
import=common/keycloak
styles=css/login.css css/acme.css
  • parent names the theme to inherit from. Anything not found in acme is looked up in the parent, then its parent, and so on.
  • styles lists CSS files, relative to resources. They are loaded in order, so your CSS comes last and wins.
  • import pulls in shared resources of another theme (for example common PatternFly assets).

After adding or changing files, restart the server, or run in development with theme caching off (--spi-theme--static-max-age=-1, --spi-theme--cache-themes=false, --spi-theme--cache-templates=false) so edits show on reload. Never leave caching disabled in production.

Overriding only what you need

Because of inheritance, a theme with a single CSS file and a logo is a complete theme. To change the page layout, copy just the template you want, for example login.ftl, from the parent into your login folder and edit it. Templates are FreeMarker (.ftl). Keep copies minimal: every copied template becomes yours to maintain through upgrades.

HTML
<#import "template.ftl" as layout>
<@layout.registrationLayout displayMessage=!messagesPerField.existsError('username','password'); section>
  <#if section = "header">
    ${msg("loginAccountTitle")}
  <#elseif section = "form">
    <form id="kc-form-login" action="${url.loginAction}" method="post">
      <input name="username" value="${(login.username!'')}" />
      <input name="password" type="password" />
      <button type="submit">${msg("doLogIn")}</button>
    </form>
  </#if>
</@layout.registrationLayout>

Real templates carry more markup for accessibility and error display, so copy the parent's file as the starting point rather than typing this from memory. Notice the pattern: ${msg("key")} looks up a text from the message bundle, and ${url.loginAction} is a value Keycloak provides.

Keycloak 26's default login theme (keycloak.v2) is built on PatternFly. Newer Keycloak releases also offer Keycloakify style tooling and a "Login v2" structure; check the release notes of your version before choosing an approach.

Resolving files through the chain

The lookup rule is simple: take the theme, look for the file, and if missing, ask the parent. Try it:

JS Stand-in: theme parent-chain resolution

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Message bundles and localization

User-visible text comes from messages_<locale>.properties files. You override single keys by redefining them in your own bundle:

PROPERTIES
loginAccountTitle=Sign in to Acme
doLogIn=Continue
usernameOrEmail=Work email

Keycloak picks the locale from the user's preference, the browser's Accept-Language, or the realm default. If a key is missing in the chosen locale, it falls back to the default locale (messages_en), then to the parent theme. Enable Internationalization in Realm settings and list supported locales to show the language switcher. Messages support placeholders , for arguments.

JS Stand-in: message lookup with locale fallback

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Styling tips

  • Start with CSS variables and a logo; change structure only if you must.
  • Test contrast and keyboard focus: login forms must remain accessible.
  • Test every page type, not just the login form: error page, OTP, password reset, required actions, consent.
  • Keep images small and served from your theme to avoid third-party requests on a sensitive page.
  • Do not load analytics or third-party scripts on login pages.

Deploying themes

For containers, copy the theme folder into /opt/keycloak/themes/ in your image build, or package it as a JAR with META-INF/keycloak-themes.json and drop it in providers/. Then run kc.sh build if you use an optimized image. Check Realm settings > Themes to select it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does parent in theme.properties do?

    Inheritance lets a small theme override only a few files; the rest come from the parent chain.
  2. 2. Which file holds editable labels such as the sign in button text?

    Message bundles supply text through the msg function in templates; overriding a key changes the label.
  3. 3. What is a sensible approach to changing only the logo and colors?

    A child theme with a stylesheet and image is small and easy to carry through upgrades.
  4. 4. Why not leave theme caching disabled in production?

    Disabling caches is a development convenience; in production it adds avoidable load and latency.

Summary

  • Themes come in types: login, account, admin, email, welcome.
  • A theme is a folder with theme.properties, templates, messages, and resources.
  • Inheritance lets you override only what changes.
  • Messages use locale bundles with fallback; templates use FreeMarker.
  • Develop with caches off, deploy with caches on.

Next: Custom Authenticators and SPIs