Developing a Customized Keycloak Theme with Keycloakify, Storybook, Tailwind CSS and more...
- 1. Introduction
- 2. Prerequisites
- 3. Project Setup
- 4. Set Up Storybook for Local Testing
- 5. Integrate Keycloakify with Vite
- 6. Customizing the Theme
- 7. Configuration Files
- 8. Building and Deploying the Theme
- 9. Advanced Customizations
- 10. Troubleshooting
1. Introduction
What is Keycloakify?
Keycloakify is a tool that allows you to create custom themes for Keycloak using modern web technologies like React.js and TypeScript. It simplifies the process of building and deploying Keycloak themes by providing a streamlined workflow and integration with tools like Vite.
Why Customize Keycloak Themes?
Customizing Keycloak themes allows you to:
- Match the look and feel of your application.
- Improve user experience with modern design and responsiveness.
- Add custom functionality to Keycloak pages (e.g., login, registration).
2. Prerequisites
Tools and Dependencies
- Node.js (v18 or higher)
- Yarn
- Keycloak (latest version)
- React.js, TypeScript, Vite, Tailwind CSS, Open Sans Font, Storybook
Setting Up the Development Environment
- Install Node.js: Download Node.js
- Install Yarn (if not already installed):
npm install -g yarn
3. Project Setup
Initialize a Vite + React + TypeScript Project
- Create a new project using Vite:
yarn create vite keycloakify-poc --template react-ts
cd keycloakify-poc
Install Required Dependencies
Install additional dependencies for Tailwind CSS, Open Sans, Storybook, and dark theme support:
yarn add keycloakify react react-dom
yarn add -D typescript vite vite-plugin-react
yarn add -D storybook @storybook/react-vite @storybook/addon-essentials @storybook/react
yarn add -D tailwindcss postcss autoprefixer @tailwindcss/postcss @tailwindcss/vite
yarn add @fontsource/open-sans
yarn add zustand
4. Set Up Storybook for Local Testing
Initialize Storybook
- Initialize Storybook:
npx storybook init
- Start Storybook:
yarn storybook
Configure Storybook
Ensure Storybook is configured to serve static files from the public directory. Update .storybook/main.ts:
import type { StorybookConfig } from "@storybook/react-vite";
const config: StorybookConfig = {
stories: [
"../src/**/*.mdx",
"../src/**/*.stories.@(js|jsx|mjs|ts|tsx)",
],
addons: [
"@storybook/addon-essentials",
"@storybook/addon-onboarding",
"@chromatic-com/storybook",
"@storybook/experimental-addon-test",
],
framework: {
name: "@storybook/react-vite",
options: {},
},
staticDirs: ["../public"], // Add this line
};
export default config;
5. Integrate Keycloakify with Vite
Create the src/keycloak-theme Directory
Keycloakify expects a keycloak-theme directory in your src folder. This directory will contain all the theme-related files.
The keycloak-theme directory will be created in the next step
Migrate the Source Code from Keycloakify Starter
To scaffold your project, you can use the Keycloakify Starter repository as a template.
- Clone the Keycloakify Starter repository into a temporary directory:
git clone https://github.com/keycloakify/keycloakify-starter tmp
- Move the
srcfolder from the cloned repository into your project'ssrc/keycloak-themedirectory:
mv tmp/src src/keycloak-theme
- Clean up the temporary directory:
rm -rf tmp
rm src/keycloak-theme/vite-env.d.ts
Rename src/main.tsx to src/main.app.tsx
The main.tsx file is the entry point for your application. Rename it to main.app.tsx to avoid conflicts with Keycloakify's main.tsx.
mv src/main.tsx src/main.app.tsx
Update the content of src/main.app.tsx to ensure it exports a valid React component:
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import App from "./App";
// Define a React component that wraps the App component
const MainApp = () => (
<StrictMode>
<App />
</StrictMode>
);
// Export the MainApp component as the default export
export default MainApp;
// Render the MainApp component to the DOM
const root = createRoot(document.getElementById("root")!);
root.render(<MainApp />);
Migrate Keycloakify Starter's main.tsx
Move the main.tsx file from the keycloak-theme directory to the root src directory:
mv src/keycloak-theme/main.tsx src/main.tsx
Update the content of src/main.tsx to lazily load the MainApp component and handle Keycloak context:
import { createRoot } from "react-dom/client";
import { lazy, StrictMode, Suspense } from "react";
import { KcPage, type KcContext } from "./keycloak-theme/kc.gen";
// Lazy load the MainApp component
const AppEntrypoint = lazy(() => import("./main.app"));
createRoot(document.getElementById("root")!).render(
<StrictMode>
{!window.kcContext ? (
<Suspense fallback={<div>Loading...</div>}>
<AppEntrypoint />
</Suspense>
) : (
<KcPage kcContext={window.kcContext} />
)}
</StrictMode>
);
declare global {
interface Window {
kcContext?: KcContext;
}
}
Update index.html
Exclude elements from the HTML <head> that are not relevant in the context of Keycloak pages. Use the keycloakify-ignore meta tags to achieve this.
Update index.html:
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="keycloakify-ignore-start">
<title>WhereQ --- Keycloakify POC</title>
<script>
window.ENV = {
API_ADDRESS: '${API_ADDRESS}',
SENTRY_DSN: '${SENTRY_DSN}'
};
</script>
<meta name="keycloakify-ignore-end">
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>
6. Customizing the Theme
Adding Tailwind CSS
- Create a
tailwind.config.jsfile:
/** @type {import('tailwindcss').Config} */
export default {
darkMode: "class",
content: [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}",
],
theme: {
extend: {
fontFamily: {
sans: ['"Open Sans"', 'sans-serif'],
},
},
},
plugins: [],
};
-
Create a
postcss.config.jsfile:export default {plugins: {"@tailwindcss/postcss": {},autoprefixer: {},},}; -
Update
vite.config.tswith thetailwindcssandkeycloakifyplugin
vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import { keycloakify } from "keycloakify/vite-plugin";
export default defineConfig({
plugins: [
react(),
tailwindcss(),
keycloakify({
accountThemeImplementation: "none",
}),
],
});
- Create a CSS file (
src/index.css) and add Tailwind directives:
@import "tailwindcss";
@import "@fontsource/open-sans";
body {
font-family: "Open Sans", sans-serif;
}
@layer components {
.dark {
@apply bg-gray-900 text-white;
}
}
NOTE: In Tailwind CSS v4 (which introduces the new tailwindcss function instead of @tailwind), so @import "tailwindcss"; is enough
- Import the CSS file in
src/main.tsx:
import { createRoot } from "react-dom/client";
import { lazy, StrictMode, Suspense } from "react";
import { KcPage, type KcContext } from "./keycloak-theme/kc.gen";
import "./index.css";
// Lazy load the MainApp component
const AppEntrypoint = lazy(() => import("./main.app"));
// The following block can be uncommented to test a specific page with `yarn dev`
// Don't forget to comment back or your bundle size will increase
import { getKcContextMock } from "./login/KcPageStory";
if (import.meta.env.DEV) {
window.kcContext = getKcContextMock({
// pageId: "register.ftl",
pageId: "login.ftl",
overrides: {}
});
}
createRoot(document.getElementById("root")!).render(
<StrictMode>
{!window.kcContext ? (
<Suspense fallback={<div>Loading...</div>}>
<AppEntrypoint />
</Suspense>
) : (
<KcPage kcContext={window.kcContext} />
)}
</StrictMode>
);
declare global {
interface Window {
kcContext?: KcContext;
}
}
NOTE: To facilitate debugging during development with yarn dev, the if (import.meta.env.DEV) block has been uncommented, enabling development-specific functionality outside of the Storybook environment.
Setting Up the Open Sans Font
- Install the Open Sans font:
yarn add @fontsource/open-sans
- Import the font in
src/index.css:
@import "@fontsource/open-sans";
body {
font-family: "Open Sans", sans-serif;
}
Implementing a Dark Theme
- Enable dark mode in
tailwind.config.js:
export default {
darkMode: "class", // or 'media' for system preference
content: [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}",
],
theme: {
extend: {},
},
plugins: [],
};
Customizing Login Page

In this case, the issue stemmed from the kc-header-wrapper class, which is part of Keycloak's original default theme (login.css). This class had predefined styles (e.g., padding, line-height, font-size, etc.) that were overriding the Tailwind CSS styles applied via inline classes in the React component. The kc- prefixed classes are part of Keycloak's default theme, and customizing them with Tailwind CSS can be challenging because Tailwind's utility classes are often overridden by these predefined styles.
Solution:
- A separate CSS file (
template.css) was created to reset the problematic properties of#kc-header-wrapperusing!important. This ensured that the styles fromlogin.csswere overridden. - The
template.cssfile was imported into theTemplate.tsxcomponent to apply the reset styles.
Final Solution Code:
/* template.css */
#kc-header-wrapper {
padding: 0 !important;
margin: 0 !important;
line-height: normal !important;
font-size: inherit !important;
text-transform: none !important;
letter-spacing: normal !important;
white-space: normal !important;
}
Customizing Keycloak Pages
- Add story
Choose
login.ftl
npx keycloakify add-story
- Eject a Keycloak page (e.g., login page):
npx keycloakify eject-page login
- Modify
KcPage.tsxaccording to theeject-pagecommand Note: Make sure import theindex.css
import { Suspense, lazy } from "react";
import type { ClassKey } from "keycloakify/login";
import type { KcContext } from "./KcContext";
import { useI18n } from "./i18n";
import DefaultPage from "keycloakify/login/DefaultPage";
import Template from "./Template";
import "../../index.css"
const UserProfileFormFields = lazy(
() => import("keycloakify/login/UserProfileFormFields")
);
const doMakeUserConfirmPassword = true;
const Login = lazy(() => import("./pages/Login"));
export default function KcPage(props: { kcContext: KcContext }) {
const { kcContext } = props;
const { i18n } = useI18n({ kcContext });
return (
<Suspense>
{(() => {
switch (kcContext.pageId) {
case "login.ftl": return (
<Login
{...{ kcContext, i18n, classes }}
Template={Template}
doUseDefaultCss={true}
/>
);
default:
return (
<DefaultPage
kcContext={kcContext}
i18n={i18n}
classes={classes}
Template={Template}
doUseDefaultCss={true}
UserProfileFormFields={UserProfileFormFields}
doMakeUserConfirmPassword={doMakeUserConfirmPassword}
/>
);
}
})()}
</Suspense>
);
}
const classes = {} satisfies { [key in ClassKey]?: string };
- Customize the ejected page (
src/pages/Login.tsx): Replace the original submit button (kcButtonClass) with tailwindcss button
<div id="kc-form-buttons" className={kcClsx("kcFormGroupClass")}>
<input type="hidden" id="id-hidden-input" name="credentialId" value={auth.selectedCredential} />
{/* <input
tabIndex={7}
disabled={isLoginButtonDisabled}
className={kcClsx("kcButtonClass", "kcButtonPrimaryClass", "kcButtonBlockClass", "kcButtonLargeClass")}
name="login"
id="kc-login"
type="submit"
value={msgStr("doLogIn")}
/> */}
<button
tabIndex={7}
disabled={isLoginButtonDisabled}
className="w-full px-4 py-2 text-white bg-gray-600 rounded-lg hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed"
name="login"
id="kc-login"
type="submit"
>
{msgStr("doLogIn")}
</button>
</div>
- Test
yarn storybook
7. Configuration Files
vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import { keycloakify } from "keycloakify/vite-plugin";
export default defineConfig({
plugins: [
react(),
tailwindcss(),
keycloakify({
accountThemeImplementation: "none",
}),
],
});
tailwind.config.js
/** @type {import('tailwindcss').Config} */
export default {
darkMode: "class",
content: [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}",
],
theme: {
extend: {},
},
plugins: [],
};
postcss.config.js
export default {
plugins: {
"@tailwindcss/postcss": {},
autoprefixer: {},
},
};
.eslintrc.js
export default {
env: {
node: true,
es2022: true,
},
parserOptions: {
ecmaVersion: "latest",
sourceType: "module",
},
rules: {
// Your ESLint rules...
},
};
tsconfig.json
{
"compilerOptions": {
"target": "ES2020",
"useDefineForClassFields": true,
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"module": "ESNext",
"skipLibCheck": true,
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true,
"jsx": "react-jsx",
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true
},
"include": ["src"],
"references": [{ "path": "./tsconfig.node.json" }]
}
8. Building and Deploying the Theme
**Make sure you added the command build-keycloak-theme in package.json
"scripts": {
"dev": "vite",
"build": "tsc -b && vite build",
"build-keycloak-theme": "npm run build && keycloakify build",
"lint": "eslint .",
"preview": "vite preview",
"storybook": "storybook dev -p 6006",
"build-storybook": "storybook build"
},
Building the Theme
Run the following command to build the theme:
yarn build-keycloak-theme
Generating the JAR File
- Package the theme into a JAR file:
yarn keycloakify build
- The JAR file will be generated in the
build/keycloak-themedirectory.
Deploying to Keycloak
- Copy the generated JAR file to your Keycloak server's
themesdirectory. - Restart Keycloak to apply the new theme.
9. Advanced Customizations
Adding Custom Pages
You can add custom pages (e.g., a custom error page) by ejecting and modifying the corresponding page:
npx keycloakify eject-page error
This will generate the necessary files for the error page in the src/keycloak-theme directory. You can then customize the page as needed.
Theming Keycloak Emails
Keycloakify also supports customizing email templates. To customize email templates:
- Eject the email template you want to modify:
npx keycloakify eject-email <email-template-name>
Replace <email-template-name> with the name of the email template (e.g., verify-email, password-reset).
- Customize the ejected email template in the
src/keycloak-themedirectory.
Localization and Internationalization
Keycloak supports multiple languages out of the box. To add localization to your theme:
-
Add language files to the
src/keycloak-theme/messagesdirectory. For example:messages_en.propertiesfor Englishmessages_fr.propertiesfor French
-
Use the
msg()function in your components to display localized text:
const Login = () => {
const { msg } = useI18n();
return (
<div>
<h1>{msg("loginTitle")}</h1>
<p>{msg("loginDescription")}</p>
</div>
);
};
- Add translations to your language files:
# messages_en.propertiesloginTitle=LoginloginDescription=Please enter your credentials.# messages_fr.propertiesloginTitle=ConnexionloginDescription=Veuillez entrer vos identifiants.
10. Troubleshooting
Common Issues and Fixes
-
Tailwind CSS Not Working:
- Ensure
postcss.config.jsandtailwind.config.jsare correctly configured. - Verify that the
@import "tailwindcss";directive is included insrc/index.css.
- Ensure
-
Font Not Loading:
- Verify the font import path in
index.css. - Ensure the
@fontsource/open-sanspackage is installed.
- Verify the font import path in
-
Dark Mode Not Applying:
- Ensure
darkMode: "class"is set intailwind.config.js. - Verify that the
darkclass is applied to the root element (e.g.,<html>).
- Ensure
-
Storybook Not Rendering Components:
- Ensure the
staticDirsconfiguration in.storybook/main.tspoints to thepublicdirectory. - Verify that the
index.cssfile is imported in your components.
- Ensure the
-
Keycloakify Build Fails:
- Ensure the
keycloak-themedirectory exists and contains valid theme files. - Check for errors in the terminal output and resolve them.
- Ensure the