API reference

The `useThunderID` hook provides access to the ThunderID authentication context in React applications. It allows you to retrieve authentication state, user information, and other context values managed by the `ThunderIDProvider`.

import { useThunderID } from '@thunderid/react'

function MyComponent() {
  const { isSignedIn, user, signIn, signOut } = useThunderID()

  return (
    <div>
      {isSignedIn ? (
        <>
          <p>Welcome, {user?.displayName}!</p>
          <button onClick={() => signOut()}>Sign Out</button>
        </>
      ) : (
        <button onClick={() => signIn()}>Sign In</button>
      )}
    </div>
  )
}

export default MyComponent

The `ThunderIDProvider` is the root context provider component that configures `@thunderid/react` and provides ThunderID context to your entire React application. It must wrap your application to enable authentication features.

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.jsx'
import { ThunderIDProvider } from '@thunderid/react'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <ThunderIDProvider
      clientId="<your-app-client-id>"
      baseUrl="https://localhost:8090"
    >
      <App />
    </ThunderIDProvider>
  </StrictMode>
)

The `ChangeCredential` component renders a form that lets a signed-in user set a new value for one of their own credentials. It collects only a new value and its confirmation, checks it against the applicable rules as the user types, and posts the change to ThunderID. It reads the rules it needs from the user type schema already resolved by `ThunderIDProvider` (`GET /users/me/meta`), so it adds no network request beyond the write itself. Every default label, placeholder, and message is built from the credential attribute's own `displayName` in that schema, so it always matches whatever an admin named it there. By default it manages the `password` credential. To manage a different one, for example a PIN declared on the user type schema, set `attribute`; render the component once per credential to let a user manage more than one. :::note `ChangeCredential` collects only a new value and its confirmation, not the account's existing value. The self-service credential write path does not verify the current value today, so asking for one would only teach the user a false sense of security. Once server-side current-value verification ships, that field returns without a breaking change to this component's public props. :::

import { ChangeCredential } from '@thunderid/react'

function AccountPage() {
  return (
    <div>
      <h2>Security</h2>
      <ChangeCredential />
    </div>
  )
}

export default AccountPage

The `Loading` component renders its children while the authentication state is being determined. It checks the current authentication state and displays a loading indicator or custom content during the initial authentication check. Once authentication is complete, it renders optional `fallback` content or nothing by default. This makes it ideal for providing user feedback during the initial app load or authentication verification.

import { Loading } from '@thunderid/react'

function App() {
  return (
    <Loading>
      <div>Checking authentication...</div>
    </Loading>
  )
}

export default App

The `SignInButton` component initiates the sign-in flow when clicked. It automatically handles loading state, error handling, and supports custom UI via render props or direct children. You can customize its behavior and appearance using the `preferences` prop, including i18n overrides.

import { SignInButton } from '@thunderid/react'

function App() {
  return <SignInButton />
}

export default App

The `SignOutButton` component signs out the current user, clears their session, and revokes authentication tokens when clicked. It automatically handles loading state, error handling, and supports custom UI via render props or direct children. You can customize its behavior and appearance using the `preferences` prop, including i18n overrides.

import { SignOutButton } from '@thunderid/react'

function App() {
  return <SignOutButton />
}

export default App

The `SignUpButton` component triggers the sign-up (registration) flow when clicked. It automatically handles loading state, error handling, and supports custom UI via render props or direct children. You can customize its behavior and appearance using the `preferences` prop, including i18n overrides.

import { SignUpButton } from '@thunderid/react'

function LandingPage() {
  return <SignUpButton />
}

export default LandingPage

The `SignedIn` component conditionally renders its children only when the user is authenticated with ThunderID. It checks the current authentication state and displays protected UI content for signed-in users, while rendering optional `fallback` content (or nothing by default) when the user is not authenticated. This makes it ideal for guarding routes or UI sections that require authentication.

import { SignedIn } from '@thunderid/react'

function App() {
  return (
    <SignedIn>
      <p>Welcome! You are signed in.</p>
    </SignedIn>
  )
}

export default App

The `SignedOut` component conditionally renders its children only when the user is not authenticated with ThunderID. It checks the current authentication state and displays content for unauthenticated users, while rendering optional `fallback` content (or nothing by default) when the user is authenticated. This makes it ideal for showing sign-in prompts, public landing pages, or content that should only be visible to guests.

import { SignedOut, SignInButton } from '@thunderid/react'

function App() {
  return (
    <SignedOut>
      <div>
        <h1>Welcome!</h1>
        <SignInButton />
      </div>
    </SignedOut>
  )
}

export default App

The `User` component is a declarative way to access the authenticated user object from the ThunderID authentication context. It uses render props to expose the user data, making it easy to display user information or conditionally render UI based on authentication state.

import { User } from '@thunderid/react'

function App() {
  return (
    <User fallback={<p>Please sign in</p>}>
      {(user) => (
        <div>
          <h1>Welcome, {user?.displayName}!</h1>
          <p>Email: {user?.email}</p>
        </div>
      )}
    </User>
  )
}

export default App

The `UserDropdown` component renders a dropdown menu with user information and common actions like viewing profile, settings, and signing out.

import { UserDropdown } from '@thunderid/react'

function Header() {
  return (
    <header>
      <UserDropdown />
    </header>
  )
}

export default Header

The `UserProfile` component renders a complete user profile management interface where users can view and edit their personal information, change passwords, manage sessions, and more.

import { UserProfile } from '@thunderid/react'

function ProfilePage() {
  return (
    <div>
      <h1>My Profile</h1>
      <UserProfile />
    </div>
  )
}

export default ProfilePage