createAuthHooks

createAuthHooks is a factory function that creates React hooks for managing Internet Identity authentication. The hooks are bound to a specific AuthenticationManager instance.

Import

import { AuthenticationManager, createAuthHooks } from "@ic-reactor/react"

Usage

import { createAuthHooks } from "@ic-reactor/react"
import { authentication } from "./reactor"

const { useAuth, useUserPrincipal, useAgentState } =
  createAuthHooks(authentication)

Parameters

Parameter	Type	Description
authentication	AuthenticationManager	The AuthenticationManager instance to bind to

AuthenticationManager is constructed from a ClientManager:

const authentication = new AuthenticationManager({ clientManager })

Pass authClient to inject a client you built yourself — IC Reactor then never constructs one:

import { AuthClient } from "@icp-sdk/auth/client"

const authentication = new AuthenticationManager({
  clientManager,
  authClient: new AuthClient(),
})

Return Value

createAuthHooks returns exactly three hooks:

Property	Type	Description
useAuth	Hook	Main hook for auth actions and state
useUserPrincipal	Hook	Current user’s Principal
useAgentState	Hook	Agent initialization state

Caution

useIdentityAttributes is not returned by createAuthHooks. It comes from the separate createIdentityAttributeHooks(identityAttributes) factory, where identityAttributes = new IdentityAttributesManager(authentication).

Complete Example

src/reactor/index.ts

import { ClientManager } from "@ic-reactor/core"
import { AuthenticationManager } from "@ic-reactor/react"
import { QueryClient } from "@tanstack/query-core"

export const queryClient = new QueryClient()

export const clientManager = new ClientManager({
  queryClient,
})

export const authentication = new AuthenticationManager({ clientManager })

src/reactor/hooks.ts

import { createAuthHooks } from "@ic-reactor/react"
import { authentication } from "./index"

export const { useAuth, useUserPrincipal, useAgentState } =
  createAuthHooks(authentication)

src/App.tsx

import { useAgentState } from "./reactor/hooks"
import { QueryClientProvider } from "@tanstack/react-query"
import { queryClient } from "./reactor"

function App() {
  const { isInitializing, error } = useAgentState()

  if (isInitializing) return <LoadingScreen />
  if (error) return <ErrorScreen error={error} />

  return (
    <QueryClientProvider client={queryClient}>
      <Router />
    </QueryClientProvider>
  )
}

Notes

Note

All reactors sharing the AuthenticationManager’s ClientManager share authentication state. When the user logs in or out, the queries of every connected canister are automatically invalidated.

Tip

The @icp-sdk/auth package is loaded through a dynamic import("@icp-sdk/auth/client") inside AuthenticationManager — in the browser it starts on construction, and prepareClient() awaits it. Bundlers put it in its own chunk, so apps that never construct an AuthenticationManager never ship it.

See Also

• Authentication Guide — In-depth auth patterns
• useAuth — Main auth hook reference
• createActorHooks — Creating actor hooks
• React Setup — Complete React configuration