Skip to main content

​
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

​
className
string
default:"''"
Additional CSS classes to apply to the container element.
​
loadingComponent
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.
​
successComponent
React.ReactNode
Custom component to display after successful authentication. If not provided, a default spinner with “Authentication complete! Redirecting…” text is shown.
​
onSuccess
() => void
Callback function that is called after successful authentication, before any redirect or window close actions.
​
onError
(error: Error) => void
Callback function that is called if an error occurs during the authentication callback.

​
Usage

​
Basic Setup

Create a callback route in your application (e.g., /callback or /auth/callback): 
import { CallbackPage } from '@ouim/logto-authkit'

function Callback() {
  return <CallbackPage />
}

export default Callback

​
With Custom Loading Component

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

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

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 (/)
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