Links
👨💻

Quick start

It's a good idea to first read this quick start section to understand the basic of how Keycloakify works.
However, we recommend you start hacking from the starter project instead of setting up Keycloakify from scratch.
Save yourself some time, have quick look at the requirements page. Windows users in particular!
yarn add keycloakify
"scripts": {
"keycloak": "yarn build && keycloakify",
}
Running yarn keycloak willl generate the keycloak-theme.jar file that you'll be able to import in Keycloak.
CSS Only customization
Component level customization
The first approach is to only customize the style of the default Keycloak login theme by providing your own class names.
src/index.tsx
import { createRoot } from "react-dom/client";
import KcApp, { defaultKcProps, getKcContext } from "keycloakify";
//We assume the file contains: ".my-class { color: red; }"
import "./index.css";
const { kcContext } = getKcContext();
if( kcContex === undefined ){
throw new Error(
"This app is a Keycloak theme" +
"It isn't meant to be deployed outside of Keycloak"
);
}
createRoot(document.getElementById("root")!).render(
<KcApp
kcContext={kcContext}
{...{
...defaultKcProps,
kcHeaderWrapperClass: "my-class",
}}
/>
);
The above snippet of code assumes you are in a react project which only purpose is to be a Keycloak theme.
If you want to make your Keycloak theme an integral part of a preexisting React app you would apply the following modification to the above snippet:
import { createRoot } from "react-dom/client";
+import { lazy, Suspense } from "react";
-import KcApp from "keycloakify/components/KcApp";
import { defaultKcProps, getKcContext } from "keycloakify";
import "./index.css";
const { kcContext } = getKcContext();
-if( kcContext === undefined ){
- throw new Error(
- "This app is a Keycloak theme" +
- "It isn't meant to be deployed outside of Keycloak"
- );
-}
+const App = lazy(() => import("<path of the root component of your app>"));
+const KcApp= lazy(()=> import("keycloakify/components/KcApp"));
createRoot(document.getElementById("root")!).render(
+ <Suspence>
+ {
+ kcContext === undefined ?
+ <App /> :
<KcApp
kcContext={kcContext}
{...{
...defaultKcProps,
kcHeaderWrapperClass: myClassName
}}
/>
+ }
+ </Suspence>
);
Result: MYREALM is red

Real world example

To give you an idea of what you can achieve by only customizing the style the style,
Here is the code that produces:
Results obtained with CSS only customization of the default theme
It is a good idea to first start with a CSS only customization, as it can be done much quicker than the component level customization, you do it once and it applies to all pages.
Once you have a CSS level customization that looks okay you can start customizing at the component level some specific pages. See an example implementing this approach.
The keycloakify components are a plain React translation of the default theme that comes with Keycloak v11.0.3.
You can download the FTL/CSS source files the components are based on with the following command:
npx -p keycloakify download-builtin-keycloak-theme
then select version 11.0.3 (Video demo).
If you want to go beyond only customizing the CSS you can re-implement some of the pages or even add new ones.
If you want to go this way checkout the demo setup provided here. If you prefer a real life example you can checkout onyxia-web's source. The web app is in production here.
See also this documentation section for more info on how to add support for extra ftl pages.

How to import the .jar in Keycloak

Before loading you theme into Keycloak you probably want to give it a spin locally. Read up the following section: