Skip to main content

API reference

The public surface of

@thunderid/react, as documented in its reference pages.

hookuseThunderID()

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`.

Returns
isSignedIn
boolean

Whether the user is currently signed in

user
User \

The authenticated user object, or `null` if not signed in

signIn
() => Promise

Initiates the sign-in flow

signOut
() => Promise

Initiates the sign-out flow

loading
boolean

Indicates if an authentication operation is in progress

error
Error \

The last error encountered during authentication, if any

currentOrganizationUnit
CurrentOrganizationUnit | null

The 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`

Example
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
hookuseFlowVariables()

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.

Returns
definitions
FlowVariableDefinition[]

The variables the flow declares for the organization unit

overrides
FlowVariableValues

The values the unit has set. A variable it has not set is absent, and its default applies

overlay
ResolvedOverlay | undefined

What the unit may do with each variable

connections
ConnectionInstance[]

The connections a CONNECTION_SELECT variable can take

isLoaded
boolean

Whether the variables, the unit's values, and its rules have all arrived

isSaving
boolean

Whether a save is in flight

error
Error | null

Why 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

saveError
Error | null

Why the last save failed

Example
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 (
<BaseFlowVariables
variables={definitions}
connections={connections}
overlay={overlay}
initialValues={overrides}
isSubmitting={isSaving}
error={saveError?.message ?? null}
onSubmit={(values, changed) => save(changed)}
/>
)
}
context<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.

Props
clientIdrequired
string

Client ID of your application

baseUrlrequired
string

The base URL of the ThunderID instance (e.g., `https://localhost:8090`)

clientSecretoptional
string

Client secret of your application. Only required for confidential clients.

scopes
string \

OpenID Connect Scopes to request during the sign-in. Defaults to `'openid profile internal_login'` if not provided.

storage
sessionStorage or localStorage \

Storage mechanism to use for session management. Defaults to `sessionStorage` if not provided.

sessionoptional
SessionConfig

Behaviour 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.

afterSignInUrloptional
string

URL to redirect to after sign-in process is completed.

afterSignUpUrloptional
string

URL to redirect to after sign-up process is completed.

afterSignOutUrloptional
string

URL to redirect to after sign-out process is completed.

tokenValidationoptional
TokenValidation

Configuration for token validation.

preferencesoptional
Preferences

Customization options for UI behavior, internationalization (i18n) and styling.

idToken
IdTokenValidation

Configuration for ID token validation

validateIssuer
boolean

Whether to validate the issuer

clockTolerance
number

Allowed clock skew in seconds

inheritFromBranding
boolean

Whether to inherit theme from ThunderID organization/application branding

mode
light \

Theme mode. `'system'` follows user's OS preference

overrides
ThemeConfig

Custom theme overrides for colors, typography, spacing, etc.

language
string

Language code for UI text (e.g., `'en-US'`, `'es-ES'`)

fallbackLanguage
string

Fallback language when translations aren't available

bundles
object

Custom translation bundles to override default text

Example
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>
)
component<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. :::

Props
attributeoptional
string

The credential attribute this instance manages, any attribute the user type schema declares `credential: true` for. Defaults to `'password'`.

cardLayoutoptional
boolean

Whether to wrap the form in a bordered card. Defaults to `false`.

classNameoptional
string

Additional CSS class names.

onSuccessoptional
() => void

Called after the credential has been changed successfully.

policyoptional
PasswordPolicy

The rules the new value must satisfy. Defaults to the applicable rules from the user type schema.

preferencesoptional
Preferences

Component-level preference overrides, including i18n.

showRequirementsoptional
boolean

Whether to render the live requirement checklist. Defaults to `true`.

titleoptional
string

Overrides the default `"Change {credential}"` heading. Pass an empty string to omit the heading entirely. Defaults to a translated, schema-derived heading.

Example
import { ChangeCredential } from '@thunderid/react'
function AccountPage() {
return (
<div>
<h2>Security</h2>
<ChangeCredential />
</div>
)
}
export default AccountPage
component<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.

Props
childrenrequired
ReactNode

Content to render during authentication loading

fallbackoptional
ReactNode

Content to render once authentication is determined

Example
import { Loading } from '@thunderid/react'
function App() {
return (
<Loading>
<div>Checking authentication...</div>
</Loading>
)
}
export default App
component<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.

Props
scopeoptional
AccessibleOrganizationUnitScope

`'siblings'` lists the accessible units that share the parent of the current unit. Omit it to list every accessible unit.

limitoptional
number

The page size. Defaults to `10`.

onSwitchoptional
(unit: AccessibleOrganizationUnit, user: User) => void

Called 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) => void

Takes over a pick: called with the unit instead of switching.

onErroroptional
(error: unknown) => void

Called with the SDK error when a switch or a load fails. The component shows its message either way.

switchOptionsoptional
SwitchOrganizationUnitOptions

Options passed to `switchOrganizationUnit`, such as `{ redirect: false }`.

titleoptional
string

Overrides the small label above the current unit. Pass an empty string to omit it.

classNameoptional
string

Additional CSS class names.

preferencesoptional
Preferences

Component-level preference overrides, including i18n.

childrenoptional
(props: OrganizationUnitSwitcherRenderProps) => ReactNode

Render function that replaces the built-in UI.

Example
import { OrganizationUnitSwitcher, SignedIn } from '@thunderid/react'
function Header() {
return (
<header>
<SignedIn>
<OrganizationUnitSwitcher scope="siblings" />
</SignedIn>
</header>
)
}
export default Header
component<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.

Props
childrenoptional
ReactNode or function

Render prop function or ReactNode for button content

preferencesoptional
Preferences

Customization options for i18n, theming, etc.

onClickoptional
function

Callback after sign-in is triggered

Example
import { SignInButton } from '@thunderid/react'
function App() {
return <SignInButton />
}
export default App
component<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.

Props
childrenoptional
ReactNode or function

Render prop function or ReactNode for button content

preferencesoptional
Preferences

Customization options for i18n, theming, etc.

onClickoptional
function

Callback after sign-out is triggered

redirectUrloptional
string

URL to redirect to after sign-out

Example
import { SignOutButton } from '@thunderid/react'
function App() {
return <SignOutButton />
}
export default App
component<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.

Props
childrenoptional
ReactNode or function

Render prop function or ReactNode for button content

preferencesoptional
Preferences

Customization options for i18n, theming, etc.

onClickoptional
function

Callback after sign-up is triggered

redirectUrloptional
string

URL to redirect to after sign-up

mode
'redirect' \

Sign-up mode

classNameoptional
string

CSS class name

styleoptional
CSSProperties

Inline styles

disabledoptional
boolean

Disable the button

Example
import { SignUpButton } from '@thunderid/react'
function LandingPage() {
return <SignUpButton />
}
export default LandingPage
component<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.

Props
childrenrequired
ReactNode

Content to render when the user is signed in

fallbackoptional
ReactNode

Content to render when not signed in

Example
import { SignedIn } from '@thunderid/react'
function App() {
return (
<SignedIn>
<p>Welcome! You are signed in.</p>
</SignedIn>
)
}
export default App
component<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.

Props
childrenrequired
ReactNode

Content to render when the user is signed out

fallbackoptional
ReactNode

Content to render when signed in

Example
import { SignedOut, SignInButton } from '@thunderid/react'
function App() {
return (
<SignedOut>
<div>
<h1>Welcome!</h1>
<SignInButton />
</div>
</SignedOut>
)
}
export default App
component<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.

Props
children
(user: User \

Render prop function that receives the user object

fallbackoptional
ReactNode

Content to render when no user is signed in

Example
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
component<UserDropdown />

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

Props
childrenoptional
ReactNode

Custom menu items (defaults to standard items)

showAvataroptional
boolean

Show user avatar (defaults to `true`)

showNameoptional
boolean

Show user name (defaults to `true`)

showEmailoptional
boolean

Show user email (defaults to `true`)

Example
import { UserDropdown } from '@thunderid/react'
function Header() {
return (
<header>
<UserDropdown />
</header>
)
}
export default Header
component<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.

Props
appearanceoptional
Appearance

Customize component appearance

sectionsoptional
string[]

Which sections to show (defaults to all sections)

Example
import { UserProfile } from '@thunderid/react'
function ProfilePage() {
return (
<div>
<h1>My Profile</h1>
<UserProfile />
</div>
)
}
export default ProfilePage
component<SharedFlowList />

The `SharedFlowList` component lists the flows shared with an organization unit, the flows it owns, or both. Selecting a flow reports it through `onSelect`, so your application decides what to open.

Props
ouIdrequired
string

The organization unit to list the flows of

ownershipoptional
'shared' | 'owned' | 'all'

Which flows to list. Defaults to shared

flowTypeoptional
string

Restricts the list to one flow type, for example AUTHENTICATION

limitoptional
number

Page size. Defaults to 20

onSelectoptional
(flow: ManagedFlow) => void

Called when a flow is chosen. Rows are selectable only when set

selectedFlowIdoptional
string

Identifier of the flow to highlight

Example
import { useState } from 'react'
import { SharedFlowList, FlowVariablesForm } from '@thunderid/react'
function DelegatedAdmin({ ouId }) {
const [selection, setSelection] = useState()
const flowId = selection?.ouId === ouId ? selection.flowId : undefined
return (
<>
<SharedFlowList ouId={ouId} selectedFlowId={flowId} onSelect={(flow) => setSelection({ ouId, flowId: flow.id })} />
{flowId && <FlowVariablesForm key={`${ouId}:${flowId}`} flowId={flowId} ouId={ouId} />}
</>
)
}
component<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.

Props
flowIdrequired
string

Identifier of the flow whose variables are configured

ouIdrequired
string

The organization unit the overrides belong to

onSavedoptional
(values: FlowVariableValues) => void

Called with the saved overrides

onCanceloptional
() => void

Called when the admin selects Cancel

ouNameoptional
string

The name of the organization unit, used in the notice and the connection hint

showScopeNoticeoptional
boolean

Shows a notice that the settings apply to the organization unit only

readOnlyoptional
boolean

Shows the variables without letting them be changed

Example
import { FlowVariablesForm } from '@thunderid/react'
function FlowSettings({ flowId, ouId }) {
return <FlowVariablesForm flowId={flowId} ouId={ouId} onSaved={() => alert('Saved')} />
}
ThunderID LogoThunderID Logo

Product

DocsAPIsSDKs
© Copyright Linux Foundation Europe.For web site terms of use, trademark policy and other project policies please see https://linuxfoundation.eu/en/policies.