Skip to main content
MoonKey’s authentication UI is highly customizable to match your application’s branding and design system. From logos and themes to custom colors and layout options, you can create a seamless experience that feels native to your app.
Want to see all customization options in action? Check out our interactive demo to explore different configurations and visual styles.

​
Quick Start

Here’s a basic example of customizing the MoonKey authentication UI: 
import { MoonKeyProvider } from '@moon-key/react-auth';

<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    appearance: {
      logo: 'https://your-app.com/logo.png',
      loginHeaderTitle: 'Welcome Back',
      loginHeaderDescription: 'Sign in to access your account'
    }
  }}
>
  {children}
</MoonKeyProvider>

​
Dashboard Configuration

Some appearance settings are configured in the MoonKey Dashboard and apply across your entire application.

​
App Name

Configure your application name in the Dashboard:
  1. Navigate to your MoonKey Dashboard
  2. Select your app from the dropdown
  3. Go to the Customization page
  4. Enter your app name in the App Name field
Your app name appears throughout MoonKey’s UI, including authentication modals and notification emails. Set your app logo in the Dashboard:
  1. Go to the Customization page
  2. Enter a URL for your logo in the Logo field
  3. Use an image with a 2:1 aspect ratio (recommended: 180px × 90px)
  4. PNG or JPG formats work best (SVGs have limited email client support)
This logo appears in authentication screens and emails. You can override it programmatically for specific screens.

​
Provider Configuration

Fine-tune the authentication UI with the appearance config in your MoonKeyProvider.

​
Logo

Set or override the logo for your authentication UI: 
<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    appearance: {
      logo: 'https://your-app.com/logo.png'
    }
  }}
>
  {children}
</MoonKeyProvider>
To hide the logo entirely, pass an empty string: 
appearance: {
  logo: ''
}

​
Login Header Title

Customize the main heading text shown on the login screen: 
<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    appearance: {
      loginHeaderTitle: 'Welcome to MyApp'
    }
  }}
>
  {children}
</MoonKeyProvider>
Tips:
  • Keep it short and welcoming (recommended: 35 characters or less)
  • Use your brand’s voice and tone
  • Make it action-oriented or inviting

​
Login Header Description

Add descriptive text below the header to guide users: 
<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    appearance: {
      loginHeaderDescription: 'Sign in to access your wallet and start trading'
    }
  }}
>
  {children}
</MoonKeyProvider>
Tips:
  • Keep it under 100 characters for optimal display
  • Clearly explain what users will do or get
  • Avoid jargon for better user comprehension

​
Hide Close Button

Control whether users can close the authentication modal: 
<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    appearance: {
      hideClose: true
    }
  }}
>
  {children}
</MoonKeyProvider>
Use cases:
  • true — Force users to complete authentication (use cautiously)
  • false — Allow users to dismiss the modal (default)
Setting hideClose: true creates a more forceful user experience. Only use this when authentication is absolutely required to proceed.

​
Complete Configuration Example

Here’s a fully customized appearance configuration using all available options: 
import { MoonKeyProvider } from '@moon-key/react-auth';

<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    appearance: {
      logo: 'https://your-app.com/logo.png',
      loginHeaderTitle: 'Welcome to MyApp',
      loginHeaderDescription: 'Sign in to access your wallet and start trading',
      hideClose: false
    }
  }}
>
  {children}
</MoonKeyProvider>

​
Advanced CSS Customization

For even deeper customization, MoonKey supports CSS variable overrides. Add these to your global CSS to customize specific UI elements: 
body {
  /* Border radius */
  --moonkey-border-radius-sm: 4px;
  --moonkey-border-radius-md: 8px;
  --moonkey-border-radius-lg: 12px;
  --moonkey-border-radius-full: 9999px;
  
  /* Background colors */
  --moonkey-color-background: #ffffff;
  --moonkey-color-background-2: #f9fafb;
  --moonkey-color-background-3: #f3f4f6;
  
  /* Foreground colors */
  --moonkey-color-foreground: #111827;
  --moonkey-color-foreground-2: #6b7280;
  --moonkey-color-foreground-3: #9ca3af;
  --moonkey-color-foreground-4: #d1d5db;
  --moonkey-color-foreground-accent: #4f46e5;
  
  /* Accent colors */
  --moonkey-color-accent: #6366f1;
  --moonkey-color-accent-light: #818cf8;
  --moonkey-color-accent-lightest: #c7d2fe;
  --moonkey-color-accent-dark: #4f46e5;
  --moonkey-color-accent-darkest: #4338ca;
  
  /* Status colors */
  --moonkey-color-success: #10b981;
  --moonkey-color-error: #ef4444;
  --moonkey-color-error-light: #fecaca;
}
Use your browser’s developer tools to inspect MoonKey’s UI and experiment with different CSS variable values in real-time.

​
Common Use Cases

​
Web3 Gaming Application

appearance: {
  logo: 'https://game.com/logo.png',
  loginHeaderTitle: 'Enter the Game',
  loginHeaderDescription: 'Connect your wallet to start playing'
}

​
DeFi Platform

appearance: {
  logo: 'https://defi.com/logo.png',
  loginHeaderTitle: 'Connect Your Wallet',
  loginHeaderDescription: 'Start trading and managing your assets',
  hideClose: true // Require authentication to proceed
}

​
NFT Marketplace

appearance: {
  logo: 'https://marketplace.com/logo.png',
  loginHeaderTitle: 'Join the Marketplace',
  loginHeaderDescription: 'Buy, sell, and trade exclusive NFTs'
}

​
Social Platform with Web3 Features

appearance: {
  logo: 'https://social.com/logo.png',
  loginHeaderTitle: 'Welcome!',
  loginHeaderDescription: 'Connect with friends and creators'
}

​
Best Practices

​
Branding Consistency

  • Use the same logo across all authentication touchpoints
  • Keep logo images consistent with your brand guidelines
  • Align header titles and descriptions with your brand voice
  • Test appearance changes across different screen sizes

​
Copywriting

  • Keep loginHeaderTitle short and welcoming (under 35 characters)
  • Make loginHeaderDescription clear and action-oriented (under 100 characters)
  • Avoid technical jargon that might confuse users
  • Use consistent terminology across your app

​
Accessibility

  • Ensure logo images have appropriate alt text
  • Test text readability on various backgrounds
  • Use clear, simple language in headers and descriptions
  • Test with screen readers and keyboard navigation

​
User Experience

  • Only use hideClose: true when authentication is absolutely required
  • Test your appearance on multiple devices and screen sizes
  • Ensure logos load quickly with optimized images
  • Provide clear value propositions in descriptions

​
Performance

  • Host logo images on a CDN for fast loading
  • Use optimized image formats (WebP when possible)
  • Keep logo file sizes under 100KB
  • Use SVGs cautiously (better for web, problematic in emails)

​
Exploring More Options

MoonKey offers extensive customization beyond what’s covered in this guide:
  • Custom modal layouts through CSS customization
  • Branded email templates configured in the dashboard
  • Multiple authentication methods with different flows
  • Advanced styling with CSS variables

View Interactive Demo

Explore all customization options with our interactive demo. Try different configurations and see changes in real-time.

​
Troubleshooting

​
Logo not displaying

Solutions:
  • Verify the logo URL is publicly accessible
  • Check image format (PNG/JPG recommended)
  • Ensure image loads in a new browser tab
  • Try with HTTPS URLs only
  • Check browser console for loading errors

​
Text not updating

Solutions:
  • Verify you’re passing loginHeaderTitle and loginHeaderDescription correctly
  • Clear browser cache and reload
  • Check for typos in property names
  • Ensure the provider is properly configured

​
Close button not hiding

Solutions:
  • Verify hideClose is set to true (boolean, not string)
  • Check that the configuration is in the correct location
  • Clear browser cache and reload
  • Test in an incognito/private window

​
CSS variables not applying

Solutions:
  • Ensure CSS is loaded before MoonKey initializes
  • Check CSS selector specificity
  • Use browser dev tools to verify variable values
  • Try applying !important for testing (not recommended for production)