icon |
---|
rocket-launch |
Keycloakify is a tool for creating custom Keycloak themes, enabling you to modify the appearance and behavior of Keycloak's user interfaces. This includes:
- Login Theme: The UI for login and registration pages, displayed to users when they attempt to log in or sign up.
- Account Theme: The account management interface, where users can update their email, change their password, and manage other account settings.
- Email Theme: The templates used by Keycloak for automated emails, such as email confirmation or password reset notifications.
- Admin Theme: The Admin Console interface, used by administrators to configure Keycloak.
For a visual preview of these UIs as they appear with Keycloak's built-in theme, visit the Storybook demonstration:
{% embed url="https://storybook.keycloakify.dev/" %}
Whether you need to apply light CSS-level customizations to the built-in UIs or perform deeper redesigns at the component level using React, Angular, or Svelte, Keycloakify is the tool to achieve your goals.
If you’d like to see Keycloakify in action, check out Neon. Clicking Login or Sign Up will take you to their Keycloakify-themed login pages.
You might be wondering why you would need a third-party tool like Keycloakify to create your custom UIs instead of relying solely on Keycloak's built-in theming system. Here are a few reasons:
- Leverage Modern Frontend Technologies: Keycloakify enables you to use TypeScript, React, Angular, Svelte, and any styling solution or component library you prefer, such as Tailwind, MUI, shadcn/ui, or plain CSS.
- Streamlined Testing: Keycloakify makes it easy to test your theme both inside and outside Keycloak, with hot reloading for a smoother development experience.
- Automated Theme Bundling: Keycloakify bundles your theme into a JAR file, ready to import directly into Keycloak.
- Version Compatibility: Themes generated with Keycloakify are backward compatible with Keycloak versions as far back as 11 and are designed to remain compatible with future Keycloak updates1.
- Built-In Real-Time Validation: Keycloakify includes real-time frontend validation by default. For example, users receive instant feedback, such as "The password must be at least 12 characters long," rather than waiting until they press the submit button.
- Community Support: We're here to help! If you're stuck or need guidance, reach out through our Discord channel or GitHub issues. We respond quickly and are happy to assist.
If you’re still unsure or want a better understanding before committing to using Keycloakify, check out this guide:
{% content-ref url="https://app.gitbook.com/s/H3WkQf6kDTNqLCk7O5D7/how-it-works" %} How does Keycloakify work? {% endcontent-ref %}
Keycloakify supports React, Angular
For Angular and Svelte users, a few considerations apply:
- Account Themes: The starting UI differs from Keycloak's default3, requiring additional adjustments.
- Admin Themes: Only React supports custom Admin UIs. However, since the Admin UI is only seen by the Keycloak instance administrator, it is rarely customized.
- Angular Setup: Keycloakify cannot be directly installed in an existing Angular project4. Themes must either be standalone projects or a subproject in a monorepo.
React provides the most seamless experience, but Angular and Svelte are fully supported for login and account themes with some extra effort, which covers the needs of most projects. Choose the framework that best suits your project and expertise. If you have any questions or concerns, feel free to ask us on our Discord channel.
Before futher reading, some practice!
{% tabs %} {% tab title="React" %}
git clone https://github.com/keycloakify/keycloakify-starter
{% endtab %}
{% tab title="Angular" %} {% hint style="danger" %} The Angular Support isn't fully stable yet. {% endhint %}
git clone https://github.com/keycloakify/keycloakify-starter-angular-vite keycloakify-starter
{% endtab %}
{% tab title="Svelte" %}
git clone https://github.com/keycloakify/keycloakify-starter-svelte keycloakify-starter
{% endtab %} {% endtabs %}
Let's create a story for the Login page and run Storybook5.
cd keycloakify-starter
yarn install # Feel free to use another package manager (if you do, remove the .yarn.lock)
npx keycloakify add-story # Select login.ftl (for example)
npm run storybook
You should now be able to see the login pages in different scenarios:
View of the storybook interface that let you preview the login page of your theme.
Now, let's apply our first CSS customization.
Create the following stylesheet:
{% code title="src/login/main.css" %}
.kcFormHeaderClass {
border: 3px solid red;
}
{% endcode %}
And import it:
{% tabs %} {% tab title="React" %}
import "./main.css";
// ...
{% endtab %}
{% tab title="Angular" %}
import "./main.css";
import { getDefaultPageComponent, type KcPage } from '@keycloakify/angular/login';
// ...
{% endtab %}
{% tab title="Svelte" %}
<script lang="ts">
import "./main.css";
import Template from '@keycloakify/svelte/login/Template.svelte';
...
{% endtab %} {% endtabs %}
This is what you should be getting:
Screenshot showing the red border being applied to the header section of the login card.
Now let's see how CSS customization works in Keycloakify:
{% content-ref url="css-customization.md" %} css-customization.md {% endcontent-ref %}
Footnotes
-
Of course, we can't guarantee that a given build of your theme will work with future major versions of Keycloak. However, our goal is to ensure that when a new Keycloak version introduces breaking changes, the only action required to make your theme compatible is updating the Keycloakify version and rebuilding your theme—no additional adjustments needed. ↩
-
The Angular support isn't stable yet. We're working on it. ↩
-
The difference exists because recent Keycloak versions use a React-based Account UI by default, which has not been ported to Angular or Svelte in Keycloakify due to the complexity involved. For Angular and Svelte projects, Keycloakify provides a base UI derived from an older version of the Keycloak Account UI, used before the switch to React. ↩
-
Keycloakify cannot be integrated directly into standard Angular projects because the Keycloakify compiler is designed to work with Vite and Webpack. However, most Angular projects today use Esbuild by default, which is not currently supported. ↩
-
Storybook is a tool that allows you to develop UI components in isolation. It is set up in the Keycloakify starter repos because it provides an good developer experience and makes it easy to quickly preview the different pages of your theme. ↩