Keycloak: Your theme is ready to edit

This documentation is part of the Customise 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 integrated 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 managed for you
• Built-in PostgreSQL database, with the administration console accessible on its own dedicated, closable port
• One-click updates keep your system up to date without manual intervention

Spend your time developing, not configuring: you can try Stackhero's Keycloak cloud solution in under 5 minutes.

Open themes/ and you will find a default/ directory. This is your active theme, already in use by your Keycloak instance. There is nothing to select: simply edit its files and see your changes applied immediately.

No prior knowledge of Keycloak themes is required. Every file already lists common settings you may want to change, showing the current Keycloak value as a commented-out example. To update a value, remove the comment mark, adjust the value, and save.

If a line remains commented, Keycloak uses its default value. This ensures your service always matches standard Keycloak behaviour, even after updates.

Updating your logo

Open default/login/resources/img/. Inside, you will see the two images currently used on your login page. Upload your own logo using the same file name, keycloak-logo-text.svg, and refresh the login page with Ctrl+F5 (Cmd+Shift+R on macOS).

That is all you need to do. There is no need to edit other files or restart your service: the update is applied as soon as you save. To change the background image, update keycloak-bg-darken.svg in the same folder.

If you wish to use different file names, you can update the references in default/login/resources/css/stackhero.css under the "Your logo" section.

Setting your colours

In stackhero.css, you will find variables already written with their current values:

:root {
  /* ---------- Colors ---------- */
  /* The buttons */
  /* --pf-v5-global--primary-color--100: #06c; */
  /* The buttons, while hovered */
  /* --pf-v5-global--primary-color--200: #004080; */
  /* The links */
  /* --pf-v5-global--link--Color: #06c; */
  /* The coloured line on top of the login box */
  /* --keycloak-card-top-color: #06c; */

To apply a change, remove the comment marks, set your colour, save, and reload the page. That is it.

While you work: Your browser caches theme CSS, images, and scripts for one hour. When testing, always reload with Ctrl+F5 to see your latest changes. Your visitors will see the update within the hour.

You have full control: the file is standard CSS and loads last, so you can override any style. Use your browser's DevTools (F12) to inspect elements. Keycloak 26 uses the PatternFly design system, so most colour variables are named --pf-v5-global--* and can be redefined in :root.

Setting your company name

No theme editing is needed for this. In your administration console, open Realm settings > General and set the Display name. This name will appear on login pages and in emails.

Changing texts, in multiple languages

You can update text without touching CSS or HTML. In default/login/messages/messages_en.properties, you will find all login form texts with their default wording. To change a line, remove the #, write your own text, and save:

loginAccountTitle=Sign in to Acme
doLogIn=Sign in
doForgotPassword=I forgot my password

Add files like messages_fr.properties for French or messages_de.properties for German, then enable those languages in the administration console under Realm settings > Localization.

Tip: The Localization tab also has a Realm overrides section, allowing you to change texts directly in the console, with no file editing or restart required. Use whichever method best suits your organisation.

Branding your emails

Keycloak sends emails for address confirmation, password resets, and user invitations. In default/email/messages/messages_en.properties, you will find the standard subject lines and messages ready to customise:

emailVerificationSubject=Confirm your Acme account
passwordResetSubject=Reset your Acme password

When editing email bodies, remember:

• Keep the {0}, {1}, {2} placeholders (Keycloak will replace them with the link, display name, and delay).
• To escape an apostrophe, write it twice (don''t).

To override email HTML, copy the template you want from the Keycloak base email theme into default/email/html/, then edit your copy.

Stackhero configures email delivery for you with SPF, DKIM, and DMARC already set up. Configure it in Realm settings > Email using the host and port provided on your service page.

If you need to reset your theme

If something goes wrong, you can delete the entire default directory and restart your service. Stackhero will create a fresh default theme, restoring the standard Keycloak appearance.

Your realms, users, and clients are stored in your database and are not affected.