> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streambird.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Appearance

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.

<Tip>
  Want to see all customization options in action? Check out our [interactive demo](https://demo.moonkey.fun/) to explore different configurations and visual styles.
</Tip>

## Quick Start

Here's a basic example of customizing the MoonKey authentication UI:

```tsx theme={null}
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.

### Logo

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:

```tsx theme={null}
<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:

```tsx theme={null}
appearance: {
  logo: ''
}
```

### Login Header Title

Customize the main heading text shown on the login screen:

```tsx theme={null}
<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:

```tsx theme={null}
<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:

```tsx theme={null}
<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)

<Warning>
  Setting `hideClose: true` creates a more forceful user experience. Only use this when authentication is absolutely required to proceed.
</Warning>

## Complete Configuration Example

Here's a fully customized appearance configuration using all available options:

```tsx theme={null}
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:

```css theme={null}
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;
}
```

<Tip>
  Use your browser's developer tools to inspect MoonKey's UI and experiment with different CSS variable values in real-time.
</Tip>

## Common Use Cases

### Web3 Gaming Application

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

### DeFi Platform

```tsx theme={null}
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

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

### Social Platform with Web3 Features

```tsx theme={null}
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

<Card title="View Interactive Demo" icon="palette" href="https://demo.moonkey.fun/">
  Explore all customization options with our interactive demo. Try different configurations and see changes in real-time.
</Card>

## 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)

## Related Documentation

* [Setup Guide](/get-started/frontend-sdks/react/setup) — Initial MoonKey configuration
* [Examples](/get-started/frontend-sdks/react/examples) — Complete code examples
* [Features](/get-started/frontend-sdks/react/features) — All SDK capabilities
* [Interactive Demo](https://demo.moonkey.fun/) — Try customization options live