Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.dynamic.xyz/docs/llms.txt

Use this file to discover all available pages before exploring further.

@dynamic-labs-sdk/react-hooks is a thin React layer over @dynamic-labs-sdk/client. It exposes a <DynamicProvider> and a set of hooks that subscribe to client state and re-render your components when that state changes.

​
Installation

npm i @dynamic-labs-sdk/react-hooks
The package has @dynamic-labs-sdk/client and react as peer dependencies.

​
Setup

Wrap your app in DynamicProvider and pass the client instance you created with createDynamicClient: 
import { DynamicProvider } from '@dynamic-labs-sdk/react-hooks';
import { dynamicClient } from './dynamicClient';

function App() {
  return (
    <DynamicProvider client={dynamicClient}>
      <YourApp />
    </DynamicProvider>
  );
}
Any hook used outside a DynamicProvider throws MissingProviderError.

​
State hooks

These hooks read directly from the client and re-render the component when the underlying state changes. They have no parameters.

​
useUser

Returns the current authenticated user, or null if no user is signed in. Re-renders on sign-in, sign-out, and profile updates. 
import { useUser } from '@dynamic-labs-sdk/react-hooks';

function ProfileBadge() {
  const user = useUser();
  if (!user) return <SignInButton />;
  return <span>{user.email ?? user.firstName}</span>;
}

​
useWalletAccounts

Returns all wallet accounts on the current session, verified and unverified. Re-renders when accounts are added, removed, or verified. 
import { useWalletAccounts } from '@dynamic-labs-sdk/react-hooks';

function WalletList() {
  const walletAccounts = useWalletAccounts();
  return (
    <ul>
      {walletAccounts.map((account) => (
        <li key={account.id}>
          {account.chain}: {account.address}
        </li>
      ))}
    </ul>
  );
}

​
useSocialAccounts

Returns the user’s linked social accounts (SocialAccount[]). Re-renders when the user’s verified credentials change. Empty array when no user is signed in. 
import { useSocialAccounts } from '@dynamic-labs-sdk/react-hooks';

function LinkedSocials() {
  const accounts = useSocialAccounts();
  return accounts.map((account) => (
    <div key={account.verifiedCredentialId}>
      {account.provider}: {account.displayName ?? account.emails[0]}
    </div>
  ));
}
See Social Account Linking for the management APIs.

​
useWalletProviders

Returns the registered wallet providers and their metadata (WalletProviderData[]). Re-renders when a provider is registered, unregistered, or its capabilities change. 
import { useWalletProviders } from '@dynamic-labs-sdk/react-hooks';

function AvailableWallets() {
  const providers = useWalletProviders();
  return providers.map((provider) => (
    <button key={provider.key}>Connect {provider.metadata.name}</button>
  ));
}

​
useInitStatus

Returns the client’s initialization status: 'uninitialized' | 'in-progress' | 'finished' | 'failed'. Use this to gate UI that depends on SDK methods until the client is ready. 
import { useInitStatus } from '@dynamic-labs-sdk/react-hooks';

function Bootstrap({ children }) {
  const initStatus = useInitStatus();
  if (initStatus !== 'finished') return <Splash />;
  return children;
}
See Initializing the Dynamic Client for init-status semantics.

​
useSessionExpiresAt

Returns the session expiration Date, or null if there is no active session. Re-renders on session updates. 
import { useSessionExpiresAt } from '@dynamic-labs-sdk/react-hooks';

function SessionCountdown() {
  const expiresAt = useSessionExpiresAt();
  if (!expiresAt) return null;
  return <span>Session ends at {expiresAt.toLocaleTimeString()}</span>;
}

​
Event hook

​
useEvent

Subscribes to any client event for the lifetime of the component. The subscription is cleaned up on unmount or when the event name changes. The listener is wrapped in a ref, so updating its identity between renders does not re-subscribe. 
import { useEvent } from '@dynamic-labs-sdk/react-hooks';

function LogoutLogger() {
  useEvent({
    event: 'logout',
    listener: ({ reason } = {}) => {
      console.log('Logged out:', reason);
    },
  });
  return null;
}
The listener signature is inferred from the event name. See the Events Catalog for the full event surface. For state-change events (userChanged, walletAccountsChanged, tokenChanged, etc.) prefer the dedicated state hooks above — they’re built on top of useEvent and avoid manual subscription bookkeeping.

​
Client access

​
useDynamicClient

Returns the DynamicClient instance from context. Throws MissingProviderError if used outside a DynamicProvider. Most code should not need this — use the state hooks for reactive state, and import client functions directly (signMessage, getBalance, etc.) for one-shot calls. 
import { useDynamicClient } from '@dynamic-labs-sdk/react-hooks';

function ClientDebugger() {
  const client = useDynamicClient();
  return <pre>{JSON.stringify(client.initStatus, null, 2)}</pre>;
}

​
Multiple clients

If your app uses more than one Dynamic client, mount a separate DynamicProvider for each subtree. Hooks resolve the closest provider, so state from one client never leaks into a tree wrapped in a different one.