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

# Login

The fastest way to integrate MoonKey is with the built-in login modal, which your application can integrate in just a few lines of code.

<Info>
  [Configure your login methods](/get-started/dashboard/login-methods) in the MoonKey Dashboard before using the login modal.
</Info>

## Opening the login modal

The `useMoonKey` hook exposes a `start` method that opens the login modal:

```tsx theme={null}
import { useMoonKey } from '@moon-key/react-auth';

export default function LoginButton() {
  const { start } = useMoonKey();

  return (
    <button onClick={() => start()}>
      Sign in
    </button>
  );
}
```

Once the user logs in, the `user` object will be populated with the authenticated user's data, and the `isAuthenticated` state will be `true`.

### Showing the login modal automatically

By default, the login modal will not appear automatically. If you want it to appear automatically on page load (e.g., for unauthenticated users), you can call `start()` in a `useEffect`:

```tsx theme={null}
import { useMoonKey } from '@moon-key/react-auth';
import { useEffect } from 'react';

export default function AutoLogin() {
  const { start, isAuthenticated } = useMoonKey();

  useEffect(() => {
    // Only show login if user is not authenticated
    if (!isAuthenticated) {
      start();
    }
  }, [isAuthenticated, start]);

  return <div>Welcome!</div>;
}
```

<Warning>
  Be careful when automatically opening the login modal. It may interrupt the user experience if triggered too frequently. Consider using user intent signals (e.g., clicking a button, navigating to a protected route) instead.
</Warning>

## Customizing the login modal

You can customize the appearance of the login modal by configuring the `appearance` prop in your `MoonKeyProvider`:

```tsx theme={null}
import { MoonKeyProvider } from '@moon-key/react-auth';

export default function App() {
  return (
    <MoonKeyProvider
      publishableKey="your_publishable_key"
      config={{
        loginMethods: ['email', 'google', 'apple', 'wallet'],
        appearance: {
          logo: 'https://your-app.com/logo.png',
          loginHeaderTitle: 'Welcome to MyApp',
          loginHeaderDescription: 'Sign in to access your account',
          hideClose: false
        }
      }}
    >
      {/* Your app */}
    </MoonKeyProvider>
  );
}
```

### Available customization options

<ParamField path="logo" type="string">
  URL to your company logo. Displayed at the top of the login modal.

  **Example:** `'https://myapp.com/logo.png'`
</ParamField>

<ParamField path="loginHeaderTitle" type="string">
  Custom title text displayed in the login modal header.

  **Default:** `'Sign in'`

  **Example:** `'Welcome Back'`
</ParamField>

<ParamField path="loginHeaderDescription" type="string">
  Custom description text displayed below the title in the login modal.

  **Default:** `'Connect your wallet or sign in with email'`

  **Example:** `'Sign in to access your account'`
</ParamField>

<ParamField path="hideClose" type="boolean">
  Whether to hide the close button on the login modal.

  **Default:** `false`

  **Example:** `true` (useful for required authentication flows)
</ParamField>

### Example: Complete customization

```tsx theme={null}
<MoonKeyProvider
  publishableKey="your_publishable_key"
  config={{
    loginMethods: ['email', 'google', 'apple'],
    appearance: {
      logo: 'https://myapp.com/brand-logo.svg',
      loginHeaderTitle: 'Welcome to MyApp',
      loginHeaderDescription: 'Create an account or sign in to continue',
      hideClose: false
    }
  }}
>
  {children}
</MoonKeyProvider>
```

## Login methods

The login modal displays authentication options based on the `loginMethods` configured in your `MoonKeyProvider`. You can enable multiple methods to give users flexibility in how they authenticate:

### Email authentication

Enable email-based passwordless authentication:

```tsx theme={null}
<MoonKeyProvider
  publishableKey="your_publishable_key"
  config={{
    loginMethods: ['email']
  }}
>
  {children}
</MoonKeyProvider>
```

When users select email login, they'll be prompted to enter their email address. MoonKey will send a one-time passcode (OTP) to verify their identity.

Learn more about [email authentication](/authentication/user-authentication/authentication-methods/email).

### OAuth providers

Enable social login with Google and Apple:

```tsx theme={null}
<MoonKeyProvider
  publishableKey="your_publishable_key"
  config={{
    loginMethods: ['google', 'apple']
  }}
>
  {children}
</MoonKeyProvider>
```

<Info>
  You must configure OAuth credentials in the [MoonKey Dashboard](/get-started/dashboard/login-methods) before using OAuth login methods.
</Info>

**Supported OAuth providers:**

* `'google'` - Google OAuth
* `'apple'` - Apple Sign In

<Info>
  Additional OAuth providers (Microsoft, Discord, GitHub, etc) are coming soon.
</Info>

Learn more about [OAuth authentication](/authentication/user-authentication/authentication-methods/oauth).

### Wallet authentication

Enable Web3 wallet login with Sign-In with Ethereum (SIWE) or Sign-In with Solana (SIWS):

```tsx theme={null}
<MoonKeyProvider
  publishableKey="your_publishable_key"
  config={{
    loginMethods: ['wallet']
  }}
>
  {children}
</MoonKeyProvider>
```

This allows users to authenticate by connecting their external wallets (MetaMask, Phantom, etc.) and signing a message.

### Multiple login methods

You can enable multiple login methods to give users options:

```tsx theme={null}
<MoonKeyProvider
  publishableKey="your_publishable_key"
  config={{
    loginMethods: ['email', 'google', 'apple', 'wallet']
  }}
>
  {children}
</MoonKeyProvider>
```

The login modal will display all enabled authentication methods, allowing users to choose their preferred option.

## Handling authentication states

After the user completes authentication, you can access their information using the `useMoonKey` hook:

```tsx theme={null}
import { useMoonKey } from '@moon-key/react-auth';

export default function UserProfile() {
  const { user, isAuthenticated, ready } = useMoonKey();

  if (!ready) {
    return <div>Loading...</div>;
  }

  if (!isAuthenticated) {
    return <div>Please sign in</div>;
  }

  return (
    <div>
      <h2>Welcome!</h2>
      <p>User ID: {user?.id}</p>
      <p>Email: {user?.email?.address}</p>
      {user?.wallet && (
        <p>Wallet: {user.wallet.address}</p>
      )}
    </div>
  );
}
```

Learn more about [authentication state](/authentication/user-authentication/authentication-state).

## Closing the login modal

Users can close the login modal by:

* Clicking the close button (X) in the top-right corner (unless `hideClose` is `true`)
* Pressing the Escape key
* Clicking outside the modal (on the backdrop)

You can also programmatically close the modal after certain actions or events in your application logic.

## Creating embedded wallets

By default, MoonKey will not automatically create an embedded wallet when a user logs in. You can configure automatic wallet creation with the `embeddedWallets.createOnLogin` option:

```tsx theme={null}
<MoonKeyProvider
  publishableKey="your_publishable_key"
  config={{
    loginMethods: ['email', 'google'],
    embeddedWallets: {
      createOnLogin: 'always' // Create wallet for every user on login
    }
  }}
>
  {children}
</MoonKeyProvider>
```

**Options:**

* `'always'` - Automatically create an embedded wallet for every user on login
* `'none'` - Don't create wallets automatically (default). You can create them manually later using `useCreateWallet`

Learn more about [automatic wallet creation](/get-started/frontend-sdks/react/advance/automatic-wallet-creation).

## Email OTP configuration

When using email authentication, you can customize the OTP verification experience:

```tsx theme={null}
<MoonKeyProvider
  publishableKey="your_publishable_key"
  config={{
    loginMethods: ['email'],
    emailOtp: {
      skipVerifiedSuccess: false,
      expiresIn: 600, // 10 minutes
      verifiedDisplayTime: 3000, // 3 seconds
      verifyEmailTitle: 'Verify your email',
      verifyEmailResendTitle: 'Resend code',
      resendCodeTime: 30, // 30 seconds before allowing resend
      verifiedNewUserMessage: 'Email verified! Setting up your account...',
      verifiedExistingUserMessage: 'Welcome back! Signing you in...',
      verifiedSuccessMessage: 'Success! You are now signed in.'
    }
  }}
>
  {children}
</MoonKeyProvider>
```

### Email OTP configuration options

<ParamField path="skipVerifiedSuccess" type="boolean" default={false}>
  Skip showing the success screen after email verification and immediately proceed to the application.
</ParamField>

<ParamField path="expiresIn" type="number" default={600}>
  Time in seconds before the OTP expires (default: 600 = 10 minutes).
</ParamField>

<ParamField path="verifiedDisplayTime" type="number" default={3000}>
  Time in milliseconds to display the success message before closing the modal (default: 3000 = 3 seconds).
</ParamField>

<ParamField path="verifyEmailTitle" type="string" default="Verify your email">
  Title text for the email verification screen.
</ParamField>

<ParamField path="verifyEmailResendTitle" type="string" default="Didn't receive a code?">
  Title text for the resend code prompt.
</ParamField>

<ParamField path="resendCodeTime" type="number" default={30}>
  Time in seconds before users can request a new OTP code (default: 30 seconds).
</ParamField>

<ParamField path="verifiedNewUserMessage" type="string" default="Email verified!">
  Success message shown to new users after verification.
</ParamField>

<ParamField path="verifiedExistingUserMessage" type="string" default="Welcome back!">
  Success message shown to existing users after verification.
</ParamField>

<ParamField path="verifiedSuccessMessage" type="string" default="Success!">
  Generic success message shown after verification.
</ParamField>

Learn more about [email authentication](/authentication/user-authentication/authentication-methods/email).

## Prefilling user information

You can prefill the login form with user information (e.g., email address) to streamline the authentication flow:

```tsx theme={null}
import { useMoonKey } from '@moon-key/react-auth';

export default function PrefillLoginButton() {
  const { start } = useMoonKey();

  const handleLogin = () => {
    start({
      prefill: {
        type: 'email',
        value: 'user@example.com'
      }
    });
  };

  return <button onClick={handleLogin}>Sign in with user@example.com</button>;
}
```

This is useful when you already know the user's email (e.g., from a marketing campaign, invitation link, or previous session).

### Prefill configuration

<ParamField path="prefill" type="object">
  Prefill configuration for the login form.

  <Expandable title="properties">
    <ParamField path="type" type="'email'" required>
      The type of prefill data. Currently only `'email'` is supported.
    </ParamField>

    <ParamField path="value" type="string" required>
      The value to prefill (e.g., the email address).
    </ParamField>
  </Expandable>
</ParamField>

## Complete example

Here's a complete example showing login modal integration with all customization options:

```tsx theme={null}
'use client';
import { MoonKeyProvider, useMoonKey } from '@moon-key/react-auth';

function App() {
  return (
    <MoonKeyProvider
      publishableKey="your_publishable_key"
      config={{
        loginMethods: ['email', 'google', 'apple', 'wallet'],
        embeddedWallets: {
          createOnLogin: 'always'
        },
        appearance: {
          logo: 'https://myapp.com/logo.png',
          loginHeaderTitle: 'Welcome to MyApp',
          loginHeaderDescription: 'Sign in to access your account',
          hideClose: false
        },
        emailOtp: {
          skipVerifiedSuccess: false,
          verifiedDisplayTime: 2000,
          verifyEmailTitle: 'Check your email',
          verifiedNewUserMessage: 'Account created successfully!',
          verifiedExistingUserMessage: 'Welcome back!'
        }
      }}
    >
      <Dashboard />
    </MoonKeyProvider>
  );
}

function Dashboard() {
  const { user, isAuthenticated, ready, start } = useMoonKey();

  if (!ready) {
    return <div>Loading...</div>;
  }

  if (!isAuthenticated) {
    return (
      <div>
        <h1>Welcome to MyApp</h1>
        <button onClick={() => start()}>Sign in</button>
      </div>
    );
  }

  return (
    <div>
      <h1>Dashboard</h1>
      <p>Welcome, {user?.email?.address}!</p>
      {user?.wallet && (
        <p>Your wallet: {user.wallet.address}</p>
      )}
    </div>
  );
}

export default App;
```

## Next steps

<CardGroup cols={2}>
  <Card title="Email OTP Screen" icon="envelope-open-text" href="/authentication/user-authentication/ui-components/email-otp">
    Customize the email verification screen
  </Card>

  <Card title="Configure Appearance" icon="palette" href="/get-started/frontend-sdks/react/advance/configure-appearance">
    Learn about all appearance options
  </Card>

  <Card title="Authentication Methods" icon="shield-check" href="/authentication/overview">
    Explore available authentication methods
  </Card>

  <Card title="Authentication State" icon="user-check" href="/authentication/user-authentication/authentication-state">
    Managing user authentication state
  </Card>
</CardGroup>