zitadel/apps/login/THEME_CUSTOMIZATION.md

Login App Theme Customization Guide

This guide helps you customize the appearance of your ZITADEL login application for a personalized user experience.

Quick Start

1. Copy the theme variables you want to customize from .env.theme.example to your .env.local file
2. Restart your application
3. Your theme changes will be applied automatically

Theme Options

🔄 Roundness (NEXT_PUBLIC_THEME_ROUNDNESS)

Controls how rounded the UI elements appear:

• edgy - Sharp, rectangular corners (modern tech, corporate)
• mid - Medium rounded corners (balanced, professional)
• full - Fully rounded corners (friendly, approachable)

📱 Layout (NEXT_PUBLIC_THEME_LAYOUT)

Controls the overall page structure:

• side-by-side - Brand section on left, form on right (desktop view)
• top-to-bottom - Brand section on top, form below (mobile-first)

📏 Spacing (NEXT_PUBLIC_THEME_SPACING)

Controls spacing and padding throughout the interface:

• regular - Standard spacing with comfortable padding (p-6, space-y-6)
• compact - Tighter spacing for information-dense layouts (p-4, space-y-4)

🎨 Appearance (NEXT_PUBLIC_THEME_APPEARANCE)

Complete design philosophies:

• flat - Minimal flat design with cards matching background color, subtle borders, and normal typography
• material - Material Design inspired with elevated cards, proper contrast, and medium typography

🖼️ Background Image (NEXT_PUBLIC_THEME_BACKGROUND_IMAGE)

Add a custom background image:

• Use local images: /images/my-background.jpg (place in public/images/)
• Use external URLs: https://example.com/background.jpg
• Leave empty for solid color backgrounds

Example Configurations

Tech Startup

NEXT_PUBLIC_THEME_ROUNDNESS=full
NEXT_PUBLIC_THEME_LAYOUT=side-by-side
NEXT_PUBLIC_THEME_SPACING=regular
NEXT_PUBLIC_THEME_APPEARANCE=material
NEXT_PUBLIC_THEME_BACKGROUND_IMAGE=/images/tech-gradient.jpg

Corporate Bank

NEXT_PUBLIC_THEME_ROUNDNESS=edgy
NEXT_PUBLIC_THEME_LAYOUT=top-to-bottom
NEXT_PUBLIC_THEME_SPACING=regular
NEXT_PUBLIC_THEME_APPEARANCE=material

Minimal SaaS

NEXT_PUBLIC_THEME_ROUNDNESS=mid
NEXT_PUBLIC_THEME_LAYOUT=side-by-side
NEXT_PUBLIC_THEME_SPACING=compact
NEXT_PUBLIC_THEME_APPEARANCE=flat

Creative Agency

NEXT_PUBLIC_THEME_ROUNDNESS=full
NEXT_PUBLIC_THEME_LAYOUT=top-to-bottom
NEXT_PUBLIC_THEME_SPACING=regular
NEXT_PUBLIC_THEME_APPEARANCE=material
NEXT_PUBLIC_THEME_BACKGROUND_IMAGE=/images/creative-workspace.jpg

Flat Design App

NEXT_PUBLIC_THEME_ROUNDNESS=mid
NEXT_PUBLIC_THEME_LAYOUT=side-by-side
NEXT_PUBLIC_THEME_SPACING=compact
NEXT_PUBLIC_THEME_APPEARANCE=flat

Material Design System

NEXT_PUBLIC_THEME_ROUNDNESS=mid
NEXT_PUBLIC_THEME_LAYOUT=side-by-side
NEXT_PUBLIC_THEME_SPACING=regular
NEXT_PUBLIC_THEME_APPEARANCE=material

Advanced Customization

For more detailed customization beyond these presets, you can:

1. Custom CSS: Add your own CSS files in the src/styles/ directory
2. Component Override: Modify the theme configuration in src/lib/theme.ts
3. Custom Appearances: Add new appearance options to the APPEARANCE_STYLES or SPACING_STYLES objects

Troubleshooting

Theme not applying

• Ensure you're using NEXT_PUBLIC_ prefix for all theme variables (NEXT_PUBLIC_THEME_ROUNDNESS, NEXT_PUBLIC_THEME_SPACING, NEXT_PUBLIC_THEME_APPEARANCE, etc.)
• Restart your development server after changing environment variables
• Check that your .env.local file is in the root of the login app directory

Background image not loading

• Verify the image path is correct
• For external URLs, ensure the domain is accessible
• Check browser console for any loading errors

Layout issues on mobile

• Test your theme on different screen sizes
• The top-to-bottom layout is generally more mobile-friendly
• Some combinations work better on certain screen sizes

Support

For additional customization needs or questions, please refer to the ZITADEL documentation or community forums.