API reference
The public surface of
@thunderid/react, as documented in its reference pages.useThunderID()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`.
isSignedInbooleanWhether the user is currently signed in
userUser \The authenticated user object, or `null` if not signed in
signIn() => PromiseInitiates the sign-in flow
signOut() => PromiseInitiates the sign-out flow
loadingbooleanIndicates if an authentication operation is in progress
errorError \The last error encountered during authentication, if any
currentOrganizationUnitCurrentOrganizationUnit | nullThe organization unit the session was issued for, read from its `ouId`, `ouHandle`, and `ouName` claims for display only, or `null`
getCurrentOrganizationUnit() => Promise<CurrentOrganizationUnit | null>Reads the current organization unit from the session's claims
switchOrganizationUnit(organizationUnitId: string, options?: SwitchOrganizationUnitOptions) => Promise<User | undefined>Signs in again bounded to another organization unit. A failed switch keeps the previous session, unless a backend reports that its session has ended, and rejects with a code from `OrganizationUnitSwitchErrorCodes`
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
useFlowVariables()The `useFlowVariables` hook loads the variables a flow declares for an organization unit, the values the unit has set, and what the unit may do with each variable. It also saves the unit's overrides. It is the data layer behind `<FlowVariablesForm />`, for building the form with your own UI.
definitionsFlowVariableDefinition[]The variables the flow declares for the organization unit
overridesFlowVariableValuesThe values the unit has set. A variable it has not set is absent, and its default applies
overlayResolvedOverlay | undefinedWhat the unit may do with each variable
connectionsConnectionInstance[]The connections a CONNECTION_SELECT variable can take
isLoadedbooleanWhether the variables, the unit's values, and its rules have all arrived
isSavingbooleanWhether a save is in flight
errorError | nullWhy the variables could not be loaded
save(values: FlowVariableValues) => Promise<FlowVariables | undefined>Replaces the unit's overrides. Never rejects, so read saveError to handle a failure
saveErrorError | nullWhy the last save failed
import { useFlowVariables, BaseFlowVariables } from '@thunderid/react'function FlowVariables({ flowId, ouId }) {const { definitions, connections, overlay, overrides, isLoaded, isSaving, save, saveError, error } =useFlowVariables({ flowId, ouId })if (error) return <p>Could not load the variables.</p>if (!isLoaded) return <p>Loading...</p>return (<BaseFlowVariablesvariables={definitions}connections={connections}overlay={overlay}initialValues={overrides}isSubmitting={isSaving}error={saveError?.message ?? null}onSubmit={(values, changed) => save(changed)}/>)}
<ThunderIDProvider />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.
clientIdrequiredstringClient ID of your application
baseUrlrequiredstringThe base URL of the ThunderID instance (e.g., `https://localhost:8090`)
clientSecretoptionalstringClient secret of your application. Only required for confidential clients.
scopesstring \OpenID Connect Scopes to request during the sign-in. Defaults to `'openid profile internal_login'` if not provided.
storagesessionStorage or localStorage \Storage mechanism to use for session management. Defaults to `sessionStorage` if not provided.
sessionoptionalSessionConfigBehaviour around the ThunderID session. Set `session.silentSignIn.beforeRedirect` to `true` to try a silent sign-in before `signIn()` redirects. The silent attempt is skipped when the sign-in options set their own `prompt`. `session.silentSignIn.timeout` (milliseconds, default `10000`) bounds how long a silent sign-in waits.
afterSignInUrloptionalstringURL to redirect to after sign-in process is completed.
afterSignUpUrloptionalstringURL to redirect to after sign-up process is completed.
afterSignOutUrloptionalstringURL to redirect to after sign-out process is completed.
tokenValidationoptionalTokenValidationConfiguration for token validation.
preferencesoptionalPreferencesCustomization options for UI behavior, internationalization (i18n) and styling.
idTokenIdTokenValidationConfiguration for ID token validation
validateIssuerbooleanWhether to validate the issuer
clockTolerancenumberAllowed clock skew in seconds
inheritFromBrandingbooleanWhether to inherit theme from ThunderID organization/application branding
modelight \Theme mode. `'system'` follows user's OS preference
overridesThemeConfigCustom theme overrides for colors, typography, spacing, etc.
languagestringLanguage code for UI text (e.g., `'en-US'`, `'es-ES'`)
fallbackLanguagestringFallback language when translations aren't available
bundlesobjectCustom translation bundles to override default text
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><ThunderIDProviderclientId="<your-app-client-id>"baseUrl="https://localhost:8090"><App /></ThunderIDProvider></StrictMode>)
<ChangeCredential />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. :::
attributeoptionalstringThe credential attribute this instance manages, any attribute the user type schema declares `credential: true` for. Defaults to `'password'`.
cardLayoutoptionalbooleanWhether to wrap the form in a bordered card. Defaults to `false`.
classNameoptionalstringAdditional CSS class names.
onSuccessoptional() => voidCalled after the credential has been changed successfully.
policyoptionalPasswordPolicyThe rules the new value must satisfy. Defaults to the applicable rules from the user type schema.
preferencesoptionalPreferencesComponent-level preference overrides, including i18n.
showRequirementsoptionalbooleanWhether to render the live requirement checklist. Defaults to `true`.
titleoptionalstringOverrides the default `"Change {credential}"` heading. Pass an empty string to omit the heading entirely. Defaults to a translated, schema-derived heading.
import { ChangeCredential } from '@thunderid/react'function AccountPage() {return (<div><h2>Security</h2><ChangeCredential /></div>)}export default AccountPage
<Loading />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.
childrenrequiredReactNodeContent to render during authentication loading
fallbackoptionalReactNodeContent to render once authentication is determined
import { Loading } from '@thunderid/react'function App() {return (<Loading><div>Checking authentication...</div></Loading>)}export default App
<OrganizationUnitSwitcher />The `OrganizationUnitSwitcher` component shows the organization unit the session is in, in a field that opens a menu of the units the signed-in user can access (`GET /users/me/ous`). Picking a unit calls `switchOrganizationUnit`, which signs in again bounded to that unit. A failed switch keeps the session, unless a backend reports that its session has ended, and shows a translated message under the field. `BaseOrganizationUnitSwitcher` is the presentational picker it renders.
scopeoptionalAccessibleOrganizationUnitScope`'siblings'` lists the accessible units that share the parent of the current unit. Omit it to list every accessible unit.
limitoptionalnumberThe page size. Defaults to `10`.
onSwitchoptional(unit: AccessibleOrganizationUnit, user: User) => voidCalled with the unit and the refreshed user after a switch that completes in place. A switch that leaves the page completes on the callback instead.
onSelectoptional(unit: AccessibleOrganizationUnit) => voidTakes over a pick: called with the unit instead of switching.
onErroroptional(error: unknown) => voidCalled with the SDK error when a switch or a load fails. The component shows its message either way.
switchOptionsoptionalSwitchOrganizationUnitOptionsOptions passed to `switchOrganizationUnit`, such as `{ redirect: false }`.
titleoptionalstringOverrides the small label above the current unit. Pass an empty string to omit it.
classNameoptionalstringAdditional CSS class names.
preferencesoptionalPreferencesComponent-level preference overrides, including i18n.
childrenoptional(props: OrganizationUnitSwitcherRenderProps) => ReactNodeRender function that replaces the built-in UI.
import { OrganizationUnitSwitcher, SignedIn } from '@thunderid/react'function Header() {return (<header><SignedIn><OrganizationUnitSwitcher scope="siblings" /></SignedIn></header>)}export default Header
<SignInButton />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.
childrenoptionalReactNode or functionRender prop function or ReactNode for button content
preferencesoptionalPreferencesCustomization options for i18n, theming, etc.
onClickoptionalfunctionCallback after sign-in is triggered
import { SignInButton } from '@thunderid/react'function App() {return <SignInButton />}export default App
<SignOutButton />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.
childrenoptionalReactNode or functionRender prop function or ReactNode for button content
preferencesoptionalPreferencesCustomization options for i18n, theming, etc.
onClickoptionalfunctionCallback after sign-out is triggered
redirectUrloptionalstringURL to redirect to after sign-out
import { SignOutButton } from '@thunderid/react'function App() {return <SignOutButton />}export default App
<SignUpButton />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.
childrenoptionalReactNode or functionRender prop function or ReactNode for button content
preferencesoptionalPreferencesCustomization options for i18n, theming, etc.
onClickoptionalfunctionCallback after sign-up is triggered
redirectUrloptionalstringURL to redirect to after sign-up
mode'redirect' \Sign-up mode
classNameoptionalstringCSS class name
styleoptionalCSSPropertiesInline styles
disabledoptionalbooleanDisable the button
import { SignUpButton } from '@thunderid/react'function LandingPage() {return <SignUpButton />}export default LandingPage
<SignedIn />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.
childrenrequiredReactNodeContent to render when the user is signed in
fallbackoptionalReactNodeContent to render when not signed in
import { SignedIn } from '@thunderid/react'function App() {return (<SignedIn><p>Welcome! You are signed in.</p></SignedIn>)}export default App
<SignedOut />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.
childrenrequiredReactNodeContent to render when the user is signed out
fallbackoptionalReactNodeContent to render when signed in
import { SignedOut, SignInButton } from '@thunderid/react'function App() {return (<SignedOut><div><h1>Welcome!</h1><SignInButton /></div></SignedOut>)}export default App
<User />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.
children(user: User \Render prop function that receives the user object
fallbackoptionalReactNodeContent to render when no user is signed in
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
<UserDropdown />The `UserDropdown` component renders a dropdown menu with user information and common actions like viewing profile, settings, and signing out.
childrenoptionalReactNodeCustom menu items (defaults to standard items)
showAvataroptionalbooleanShow user avatar (defaults to `true`)
showNameoptionalbooleanShow user name (defaults to `true`)
showEmailoptionalbooleanShow user email (defaults to `true`)
import { UserDropdown } from '@thunderid/react'function Header() {return (<header><UserDropdown /></header>)}export default Header
<UserProfile />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.
appearanceoptionalAppearanceCustomize component appearance
sectionsoptionalstring[]Which sections to show (defaults to all sections)
import { UserProfile } from '@thunderid/react'function ProfilePage() {return (<div><h1>My Profile</h1><UserProfile /></div>)}export default ProfilePage
<FlowVariablesForm />The `FlowVariablesForm` component lets a delegated admin override the variables a flow declares for their organization unit. It loads the variables the flow shares with the unit and the values the unit has set, shows them as a form, and saves the values that differ from their defaults.
flowIdrequiredstringIdentifier of the flow whose variables are configured
ouIdrequiredstringThe organization unit the overrides belong to
onSavedoptional(values: FlowVariableValues) => voidCalled with the saved overrides
onCanceloptional() => voidCalled when the admin selects Cancel
ouNameoptionalstringThe name of the organization unit, used in the notice and the connection hint
showScopeNoticeoptionalbooleanShows a notice that the settings apply to the organization unit only
readOnlyoptionalbooleanShows the variables without letting them be changed
import { FlowVariablesForm } from '@thunderid/react'function FlowSettings({ flowId, ouId }) {return <FlowVariablesForm flowId={flowId} ouId={ouId} onSaved={() => alert('Saved')} />}