A modern, production-ready custom theme for Keycloak built with React, TypeScript, and shadcn/ui components. This theme provides a visually stunning authentication experience with glassmorphism effects, smooth animations, and a fully responsive design.
-
Component Library
- Built with shadcn/ui components
- Customizable Field components for form inputs
- Consistent design system using Tailwind CSS
-
Developer Experience
- TypeScript for type safety
- Storybook for component development - View Live Storybook
- Hot module replacement with Vite
- ESLint and Prettier for code quality
- Node.js >= 18.0.0 or >= 20.0.0
- pnpm >= 8.15.2
- Maven >= 3.1.1 (for building the theme)
- Java >= 7 (for Maven)
# Install dependencies
pnpm installNote: If you use a different package manager (npm, yarn), make sure to delete pnpm-lock.yaml first.
Start the development server with hot reload:
pnpm devThe theme will be available at http://localhost:5173 (or the port Vite assigns).
View and develop components in isolation:
pnpm storybookStorybook will be available at http://localhost:6006.
Live Storybook: https://cloakwise-io.github.io/keycloak-custom-theme
To build the Keycloak theme JAR files, you need Maven installed:
macOS:
brew install mavenDebian/Ubuntu:
sudo apt-get install mavenWindows:
choco install openjdk
choco install mavenOr download Maven from maven.apache.org.
Build the theme:
pnpm run build-keycloak-themeThis command will:
- Build the React application (
pnpm run build) - Generate Keycloak theme JAR files using Keycloakify
By default, Keycloakify generates multiple JAR files for different Keycloak versions. You can customize this behavior in the Keycloakify documentation.
The generated JAR files will be in the dist_keycloak/ directory:
keycloak-theme-for-kc-22-to-25.jar- For Keycloak 22-25keycloak-theme-for-kc-all-other-versions.jar- For other versions
For detailed instructions on testing your theme locally, see the Keycloakify testing documentation.
All UI components are located in src/components/ui/ and can be customized to match your brand:
- Colors: Modify Tailwind CSS variables in your CSS files
- Components: Edit component files in
src/components/ui/ - Layout: Customize
src/components/overrides/auth-page-layout.tsx - Pages: Modify page components in
src/login/pages/
- Create a new page component in
src/login/pages/ - Add a case in
src/login/KcPage.tsxto route to your new page - Use the
Templatecomponent for consistent layout
The theme uses Tailwind CSS for styling. Key files:
src/login/global.css- Global stylessrc/login/custom.css- Custom theme styles
For more customization strategies, see the Keycloakify customization documentation.
Initialize the account management theme:
npx keycloakify initialize-account-themeInitialize the email theme:
npx keycloakify initialize-email-themeStart Keycloak with Docker Compose:
docker compose up --buildKeycloak will be available at http://localhost:8080 with the admin credentials:
- Username:
admin - Password:
adminpassword
This project includes a GitHub Actions workflow that automatically builds and publishes theme JAR files as GitHub release artifacts.
To enable the workflow:
- Go to your repository on GitHub
- Navigate to
Settings>Actions>Workflow permissions - Select
Read and write permissions
To release a new version:
- Update the version in
package.json - Push to the repository
- The workflow will automatically build and publish the theme
For deploying Keycloak on Kubernetes, follow the official guide: Kubernetes Deployment Guide
- Build the theme:
pnpm run build-keycloak-theme - Copy the JAR files from
dist_keycloak/to your Keycloakthemes/directory - Restart Keycloak
- Live Storybook - Interactive component documentation
- Keycloakify Documentation
- shadcn/ui Documentation
- Tailwind CSS Documentation
- Keycloak Documentation
- Fork the repository
- Create a feature branch
- Make your changes
- Run linting:
pnpm format - Submit a pull request