Keycloak: Understanding Keycloak theme structure

This documentation is part of the Customize the appearance guide. You can view the complete guide here: Easily brand your Keycloak login pages, account console, and emails on Stackhero: set your colours, logo, texts, and even create fully custom themes using the built-in online editor..

👋 Welcome to the Stackhero documentation!

Stackhero offers a Keycloak cloud service that makes it easy to deploy a production-ready identity provider in just 2 minutes:

• Unlimited users, realms, and clients
• Supports OpenID Connect, OAuth 2.0, SAML 2.0, social login, LDAP, and Active Directory federation
• Custom domain name with built-in HTTPS for secure access (for example, https://login.your-company.com)
• Custom themes: easily brand your login pages, account console, and emails with the included online editor
• Dedicated email server with SPF, DKIM, and DMARC, so account confirmations and password resets are handled for you
• Built-in PostgreSQL database, with the administration console available on its own dedicated, closable port
• One-click updates keep your system up to date without manual intervention

Spend your time building, not configuring: you can try out Stackhero's Keycloak cloud solution in less than 5 minutes.

A theme is a directory containing subdirectories for each type of page:

themes/
  acme/
    login/                             # User sign-in pages
      theme.properties                 # Theme inheritance and CSS includes
      resources/css/stackhero.css      # Your CSS
      resources/img/logo.svg           # Your images
      messages/messages_en.properties  # Your texts
    account/                           # User profile management
    admin/                             # Administration console appearance
    email/                             # Email templates

Themes are inherited from standard Keycloak themes, overriding only what you need. A typical login/theme.properties looks like this:

parent=keycloak.v2
styles=css/styles.css css/stackhero.css

• parent sets the base theme.
• styles lists the CSS files to load. Place your CSS last to ensure your changes take effect.

The styles list replaces the parent theme's list, not extends it. Always include the parent's stylesheet (css/styles.css) or your page will lose its default styling.

You only need FreeMarker templates (.ftl files) if you want to change the HTML structure. For colours, logos, backgrounds, texts, and languages, no template editing is required. For more details, see the Keycloak themes documentation.