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

# CallbackPage

> Handles the OAuth callback after authentication with Logto.

## Overview

The `CallbackPage` component handles the OAuth callback flow after a user completes authentication with Logto. It processes the authorization code, exchanges it for tokens, and redirects the user appropriately.

## Props

<ParamField path="className" type="string" default="''">
  Additional CSS classes to apply to the container element.
</ParamField>

<ParamField path="loadingComponent" type="React.ReactNode">
  Custom component to display while the callback is being processed. If not provided, a default loading spinner with "Signing you in..." text is shown.
</ParamField>

<ParamField path="successComponent" type="React.ReactNode">
  Custom component to display after successful authentication. If not provided, a default spinner with "Authentication complete! Redirecting..." text is shown.
</ParamField>

<ParamField path="onSuccess" type="() => void">
  Callback function that is called after successful authentication, before any redirect or window close actions.
</ParamField>

<ParamField path="onError" type="(error: Error) => void">
  Callback function that is called if an error occurs during the authentication callback.
</ParamField>

## Usage

### Basic Setup

Create a callback route in your application (e.g., `/callback` or `/auth/callback`):

```tsx theme={null}
import { CallbackPage } from '@ouim/logto-authkit'

function Callback() {
  return <CallbackPage />
}

export default Callback
```

### With Custom Loading Component

```tsx theme={null}
import { CallbackPage } from '@ouim/logto-authkit'

function Callback() {
  return (
    <CallbackPage 
      loadingComponent={
        <div className="text-center">
          <h1>Please wait...</h1>
          <p>Authenticating your account</p>
        </div>
      }
    />
  )
}
```

### With Callbacks

```tsx theme={null}
import { CallbackPage } from '@ouim/logto-authkit'
import { useRouter } from 'next/navigation'

function Callback() {
  const router = useRouter()

  return (
    <CallbackPage 
      onSuccess={() => {
        console.log('Authentication successful!')
        // Optionally track analytics, etc.
      }}
      onError={(error) => {
        console.error('Authentication failed:', error)
        router.push('/login?error=auth_failed')
      }}
    />
  )
}
```

### Fully Customized

```tsx theme={null}
import { CallbackPage } from '@ouim/logto-authkit'

function Callback() {
  return (
    <CallbackPage 
      className="custom-callback-page"
      loadingComponent={
        <div className="flex flex-col items-center gap-4">
          <div className="loader" />
          <h2>Signing you in...</h2>
        </div>
      }
      successComponent={
        <div className="flex flex-col items-center gap-4">
          <svg className="checkmark" /* ... */ />
          <h2>Success! Redirecting...</h2>
        </div>
      }
      onSuccess={() => {
        // Track authentication success
        analytics.track('user_signed_in')
      }}
      onError={(error) => {
        // Track authentication error
        analytics.track('auth_error', { error: error.message })
      }}
    />
  )
}
```

## Behavior

### Standard Flow

1. User is redirected to this page after authenticating with Logto
2. The component exchanges the authorization code for tokens
3. `onSuccess` callback is called (if provided)
4. User is redirected to the home page (`/`)

### Popup Flow

When authentication happens in a popup window:

1. Component detects it's running in a popup (via `window.opener` or `sessionStorage`)
2. Exchanges authorization code for tokens
3. `onSuccess` callback is called (if provided)
4. Sends `SIGNIN_SUCCESS` message to parent window via `postMessage`
5. Falls back to `localStorage` if `postMessage` fails
6. Closes the popup window after a 100ms delay

### Error Handling

If an error occurs during the callback:

1. Error is logged to console
2. `onError` callback is called (if provided)
3. Loading state continues (manual error handling required)

## Notes

* The component must be used within an `AuthProvider` context
* The callback URL must be registered in your Logto application settings
* The component handles both full-page redirects and popup authentication flows automatically
* A `simple_logto_popup_flow` sessionStorage flag persists the popup state across redirects
* The component prevents duplicate callback execution using a ref
* Spin animation keyframes are injected into the document head automatically

## Related

* [SignInPage](/logto-authkit/api/components/sign-in-page) - Initiates the sign-in flow
* [AuthProvider](/logto-authkit/api/components/auth-provider) - Required context provider