Keycloakify Shadcn Starter

A modern, production-ready Keycloak login theme built with React, TypeScript, Tailwind CSS v4, shadcn/ui, and Keycloakify v11.

npm Package: @oussemasahbeni/keycloakify-login-shadcn

Features

Modern UI - Beautiful, responsive design using Tailwind CSS v4 and shadcn/ui components
Dark Mode - Built-in dark/light/system theme toggle with persistent preferences
Multi-language Support - i18n ready with English, French, and Arabic translations (RTL supported)
Custom Email Templates - Styled email templates using jsx-email for all Keycloak events
Complete Login Flow - All 35+ Keycloak login pages fully customized
Social Login Providers - Pre-styled icons for 16+ OAuth providers (Google, GitHub, Microsoft, etc.)
Storybook Integration - Visual testing and documentation for all components
Vite Powered - Fast development with HMR and optimized builds
Type-Safe - Full TypeScript support throughout the codebase

Quick Start with npm

Get started quickly by using the published npm package in your own project.

Step 1: Create a new Vite + React + TypeScript project

pnpm create vite

When prompted:

Project name: keycloak-theme (or your preferred name)
Select a framework: Choose React
Select a variant: Choose TypeScript

cd keycloak-theme

Step 2: Install dependencies

pnpm add keycloakify @oussemasahbeni/keycloakify-login-shadcn
pnpm install

Step 3: Initialize Keycloakify

npx keycloakify init

When prompted:

Which theme type would you like to initialize? Select (x) login
Do you want to install the Stories? Select (x) Yes (Recommended)

Step 4: Configure Vite

Update your vite.config.ts to include Tailwind CSS, path aliases, and the Keycloakify plugin:

import react from "@vitejs/plugin-react";
import { keycloakify } from "keycloakify/vite-plugin";
import { defineConfig } from "vite";
import path from "node:path";
import tailwindcss from "@tailwindcss/vite";

// https://vite.dev/config/
export default defineConfig({
    plugins: [
        react(),
        tailwindcss(),
        keycloakify({
            accountThemeImplementation: "none"
        })
    ],
    resolve: {
        alias: {
            "@": path.resolve(__dirname, "./src")
        }
    }
});

Step 5: Configure TypeScript paths

Add the path alias to your tsconfig.app.json:

{
    "compilerOptions": {
        "paths": {
            "@/*": ["./src/*"]
        }
    }
}

Step 6: Run Storybook and build

# Run Storybook for component development and testing
pnpm storybook

# Build the Keycloak theme JAR file
pnpm build-keycloak-theme

That's it! You now have a fully functional Keycloak login theme using the published package.

Development (for contributors)

If you want to clone this repository and develop/customize the theme locally:

Prerequisites

Node.js 18+
pnpm (or npm/yarn)
Maven (for building the theme JAR)

Clone and Install

# Clone the repository
git clone https://github.com/Oussemasahbeni/keycloakify-shadcn-starter.git
cd keycloakify-shadcn-starter

# Install dependencies
pnpm install

Development Commands

# Start development server with hot reload
pnpm dev

# Run Storybook for component development
pnpm storybook

# Preview email templates
pnpm emails:preview

# Build the Keycloak theme JAR
pnpm build-keycloak-theme

Supported Pages

This theme includes custom implementations for all Keycloak login pages:

Authentication	Account Management	Security
Login	Register	WebAuthn Authenticate
Login with Username	Update Profile	WebAuthn Register
Login with Password	Update Email	Configure TOTP
Login OTP	Delete Account	Recovery Codes
Login with Passkeys	Logout Confirm	Reset OTP
OAuth Grant	Terms & Conditions	X509 Info
Device Verification	Select Organization	Delete Credential

Branding

Logo: Replace src/login/assets/img/auth-logo.svg with your company logo
Colors: Modify CSS variables in src/login/index.css
Fonts: Update font imports in src/login/assets/fonts/

Internationalization

Add or modify translations in src/login/i18n.ts:

.withCustomTranslations({
    en: {
        welcomeMessage: "Welcome to Your App",
        loginAccountTitle: "Login to your account",
        // ... more translations
    },
    fr: { /* French translations */ },
    ar: { /* Arabic translations */ }
})

UI Components

The theme uses shadcn/ui components located in src/components/ui/:

alert.tsx - Alert messages
button.tsx - Buttons with variants
card.tsx - Card containers
checkbox.tsx - Checkbox inputs
input.tsx - Text inputs
label.tsx - Form labels
dropdown-menu.tsx - Dropdown menus
radio-group.tsx - Radio button groups
tooltip.tsx - Tooltips

Email Templates

Custom email templates are built with jsx-email and support multiple languages.

Available Templates

Template	Description
`email-verification.tsx`	Email verification
`password-reset.tsx`	Password reset link
`executeActions.tsx`	Required actions
`identity-provider-link.tsx`	IDP linking
`org-invite.tsx`	Organization invitation
`event-login_error.tsx`	Login error notification
`event-update_password.tsx`	Password change notification
`event-update_totp.tsx`	TOTP configuration notification
And more...

Preview Emails Locally

pnpm emails:preview

Email Locales

Translations are in src/email/locales/{locale}/translation.json:

en/ - English
fr/ - French
ar/ - Arabic

Building for Production

Install Maven

Required for building the Keycloak theme JAR file.

macOS: brew install maven
Ubuntu/Debian: sudo apt-get install maven
Windows: choco install openjdk && choco install maven

Build the Theme

pnpm build-keycloak-theme

The built theme will be output as a .jar file in the dist_keycloak/ directory.

Deploy to Keycloak

Copy the .jar file to your Keycloak's providers/ directory
Restart Keycloak
Go to Keycloak Admin Console → Realm Settings → Themes
Select your custom theme from the dropdown

Testing

Storybook

Run Storybook for visual testing and component documentation:

pnpm storybook

Local Keycloak Testing

For local testing with a Keycloak instance, see the Keycloakify documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License.

Acknowledgments

Keycloakify - For making Keycloak theming with React possible
shadcn/ui - For the beautiful UI components
Tailwind CSS - For the utility-first CSS framework
jsx-email - For React email templates

Package Information

npm: @oussemasahbeni/keycloakify-login-shadcn
GitHub: Oussemasahbeni/keycloakify-shadcn-starter

Name		Name	Last commit message	Last commit date
Latest commit History 133 Commits
.github/workflows		.github/workflows
.storybook		.storybook
public		public
scripts		scripts
src		src
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
README.md		README.md
components.json		components.json
eslint.config.js		eslint.config.js
index.html		index.html
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation