}\n \n );\n}\n\nconst root = document.getElementById('root');\nif (!root) throw new Error('Missing root element');\n\ncreateRoot(root).render(\n \n \n ,\n);\n```\n\n`OidcProvider` processes the callback route; do not call `loginCallbackAsync()` yourself inside this React setup. `login('/')` selects the application destination after authentication, not the registered callback URL.\n\nThis example uses browser storage. For optional token isolation, follow the [service-worker setup](#service-worker).\n\n```mermaid\nflowchart LR\n UI[\"React components and hooks\"] --> Provider[\"OidcProvider\"]\n Provider --> Client[\"@axa-fr/oidc-client\"]\n Client --> IdP[\"OIDC identity provider\"]\n Client --> SW[\"Optional service worker\"]\n SW --> API[\"Trusted API\"]\n Client --> Fetch[\"OIDC fetch without worker\"]\n Fetch --> API\n```\n\n## Protect components\n\n`OidcSecure` starts login when there is no authenticated session and renders its children only after authentication:\n\n```tsx\nimport { OidcSecure } from '@axa-fr/react-oidc';\n\nexport function PrivatePage(): React.JSX.Element {\n return (\n \n
Account
\n \n );\n}\n```\n\nPlace it beneath `OidcProvider`. You can protect the whole application, a route element, or a smaller component. Optional props are `callbackPath`, authorization `extras`, and `configurationName`.\n\nThe higher-order component (HOC) equivalent is:\n\n```tsx\nimport { withOidcSecure } from '@axa-fr/react-oidc';\n\nfunction AccountDetails(): React.JSX.Element {\n return
Account details
;\n}\n\nexport const ProtectedAccountDetails = withOidcSecure(AccountDetails, '/account');\n```\n\nIts signature is `withOidcSecure(Component, callbackPath?, extras?, configurationName?)`.\n\nThese components gate the UI; your APIs must independently validate tokens and enforce authorization.\n\n## Call protected APIs\n\n`useOidcFetch()` returns a fetch wrapper that attaches the access token (or a service-worker placeholder) and integrates with renewal. Use it only for trusted API URLs, not arbitrary user-supplied destinations.\n\n```tsx\nimport { useState } from 'react';\nimport { useOidcFetch } from '@axa-fr/react-oidc';\n\nexport function ProfileRequest(): React.JSX.Element {\n const { fetch: oidcFetch } = useOidcFetch();\n const [status, setStatus] = useState('Ready');\n\n const loadProfile = async (): Promise => {\n setStatus('Loading…');\n try {\n const response = await oidcFetch('https://api.example.com/profile');\n if (!response.ok) {\n throw new Error(`API request failed with status ${response.status}`);\n }\n setStatus('Profile request succeeded');\n } catch {\n setStatus('Could not load the profile');\n }\n };\n\n return (\n <>\n \n
{status}
\n \n );\n}\n```\n\nRender protected API consumers beneath `OidcSecure`, or wait until `useOidc().isAuthenticated` is true. Check `response.ok`: ordinary HTTP error responses do not automatically reject.\n\n| API | Arguments / result |\n| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |\n| `useOidcFetch(fetch?, configurationName?, demonstratingProofOfPossession?)` | Returns `{ fetch }`; defaults to browser fetch and configuration `'default'`. |\n| `withOidcFetch(fetch?, configurationName?, demonstratingProofOfPossession?)(Component)` | Injects a `fetch` prop into a component. |\n\nFor example, `withOidcFetch()(ProfileComponent)` supplies the same wrapper through props instead of a hook.\n\n## User information and token hooks\n\n### User information\n\n`useOidcUser()` reads the provider's user-info endpoint and exposes loading state. The exported enum is **`OidcUserStatus`**:\n\n```tsx\nimport { OidcUserStatus, useOidcUser } from '@axa-fr/react-oidc';\n\nexport function UserGreeting(): React.JSX.Element {\n const { oidcUser, oidcUserLoadingState } = useOidcUser();\n\n switch (oidcUserLoadingState) {\n case OidcUserStatus.Loading:\n return
Loading profile…
;\n case OidcUserStatus.Unauthenticated:\n return
Please sign in.
;\n case OidcUserStatus.LoadingError:\n return
Could not load your profile.
;\n default:\n return
Hello, {oidcUser?.name ?? 'there'}.
;\n }\n}\n```\n\nThe hook also returns `reloadOidcUser()`. Use `useOidcUser(configurationName?, demonstratingProofOfPossession?)` for custom claims, where `MyUserInfo` extends `OidcUserInfo`.\n\n### Hook reference\n\n| Hook | Return values |\n| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |\n| `useOidc(configurationName?)` | `isAuthenticated`, `login`, `logout`, `renewTokens`. |\n| `useOidcUser(configurationName?, demonstratingProofOfPossession?)` | `oidcUser`, `oidcUserLoadingState`, `reloadOidcUser`. |\n| `useOidcAccessToken(configurationName?)` | `accessToken`, `accessTokenPayload`, and, when enabled, `generateDemonstrationOfProofOfPossessionAsync`. |\n| `useOidcIdToken(configurationName?)` | `idToken`, `idTokenPayload`. |\n\n`login(callbackPath?, extras?, silentLoginOnly?, scope?)`, `logout(callbackPath?, extras?)`, and `renewTokens(extras?)` return promises.\n\nPrefer `useOidcFetch` over manually building authorization headers. When worker token hiding is enabled, `accessToken` is a placeholder rather than the real token. Do not render or log raw tokens, and treat user claims as personal data. An ID token identifies the user to the client; it is not a replacement for an API access token.\n\n## Service worker\n\nEnsure your application's static-assets directory exists (`public` below), then install the worker assets:\n\n```sh\nnode ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public\n```\n\nKeep the generated `OidcServiceWorker.js` synchronized with package updates. For example, merge this into your application's `package.json`:\n\n```json\n{\n \"scripts\": {\n \"postinstall\": \"node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public\"\n }\n}\n```\n\nThen:\n\n1. Configure `public/OidcTrustedDomains.js` with your provider and API destinations.\n2. Add `service_worker_relative_url: '/OidcServiceWorker.js'` to the OIDC configuration.\n3. Set `service_worker_only: true` if login must not fall back to browser token storage.\n4. Serve the worker over HTTPS (or localhost) with a scope that covers the application.\n\nFollow the [core service-worker guide](../oidc-client/README.md#service-worker) for a trusted-domain example, all options, token-exposure choices, and fallback behavior.\n\n**Multi-tab login:** when `allowMultiTabLogin: true` is set in a trusted-domain entry, use `useOidcFetch()` or `withOidcFetch()` for protected API calls. Their tab-specific placeholder identifies the session to the worker. Plain fetch or a default Axios request cannot supply that marker and may result in HTTP 401.\n\nThe worker can hide access and refresh tokens from application JavaScript, but it does **not** prevent XSS or stop injected code from making requests through your application. It does not hide all identity information. Keep normal XSS defenses and avoid broad trusted-domain rules.\n\n## Configuration, renewal, PAR, and DPoP\n\n`OidcProvider` accepts the same `OidcConfiguration` as the vanilla client. Keep provider props, such as custom components and routing callbacks, outside that configuration object.\n\n- **Configuration:** see the [core configuration reference](../oidc-client/README.md#configuration) for required fields, storage, discovery, timeouts, logout, and session monitoring.\n- **Renewal:** automatic renewal is enabled by default. For `TokenAutomaticRenewMode.AutomaticOnlyWhenFetchExecuted`, use `useOidcFetch`/`withOidcFetch` so requests trigger renewal. See [renewal behavior and strict renewal](../oidc-client/README.md#token-renewal).\n- **Silent login:** add a distinct `silent_redirect_uri` if required. The provider handles its silent-login routes. Provider and browser cookie policies can prevent iframe login.\n- **PAR:** set `par: 'auto'` or `'required'` in `configuration`; the default is `'disabled'`. `auto` uses PAR when an endpoint is advertised; missing required endpoints fail before navigation. Once selected, PAR errors never silently downgrade. See [full PAR semantics, errors, and CORS requirements](../oidc-client/README.md#pushed-authorization-requests-par).\n- **DPoP:** enable `demonstrating_proof_of_possession` and use `useOidcFetch(undefined, 'default', true)` or `withOidcFetch(undefined, 'default', true)`. For user info, use `useOidcUser('default', true)`. See [DPoP and worker-specific settings](../oidc-client/README.md#dpop). Both the identity provider and resource server must support it.\n\n## Custom components and provider options\n\nReplace built-in status screens with your own components. These are **provider props**, not fields inside `configuration`:\n\n```tsx\nconst Loading = (): React.JSX.Element =>
Sign-in failed. Please return to the sign-in page and try again.
\n);\n\n\n \n;\n```\n\n| Provider prop | Purpose |\n| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| `configuration`, `configurationName` | Client configuration and its name (`'default'` by default). |\n| `loadingComponent` | Session restoration/loading screen. |\n| `loadingTimeoutComponent` | Screen shown when the loading watchdog expires. |\n| `authenticatingComponent` | Screen shown while starting login. |\n| `authenticatingErrorComponent` | Login or callback failure screen. |\n| `callbackSuccessComponent` | Screen shown after a successful callback. |\n| `sessionLostComponent` | Session-loss screen. |\n| `serviceWorkerNotSupportedComponent` | Unavailable-worker screen when worker-only mode is required. |\n| `onSessionLost` | Handles session loss instead of displaying the built-in session-loss flow. |\n| `onLogoutFromAnotherTab`, `onLogoutFromSameTab` | React to logout events. |\n| `onEvent(configurationName, eventName, data)` | Observe client events; avoid logging complete payloads. |\n| `withCustomHistory` | Returns a history adapter with `replaceState(url, stateHistory?)`. |\n| `navigateAfterCallback(callbackPath)` | Async callback to perform post-login navigation; takes precedence over the history adapter for this navigation. |\n| `getFetch` | Supplies a custom fetch implementation for the underlying client. |\n| `location` | Custom `ILOidcLocation` adapter. |\n\nCustom status components receive `configurationName`. Set `configuration.loading_timeout_ms` to change the default 30-second loading watchdog, or a nonpositive value to disable it. See [`OidcProviderProps`](./src/OidcProvider.tsx) for the full type.\n\n## Routing and Next.js\n\n### Client-side routers\n\nThe default navigation uses the browser History API and dispatches `popstate`. Keep `OidcProvider` mounted on callback URLs. Protect route elements with `OidcSecure`; no particular router package is required.\n\nFor a router-specific integration, provide `navigateAfterCallback` to perform and await the router's navigation, or `withCustomHistory` to replace the default history adapter. These options belong on `OidcProvider`.\n\nThe library retains hash-route callback matching for legacy integrations, but OAuth redirect URIs must not contain a fragment. Prefer path-based callback URLs for new deployments, even if the rest of the application uses a hash router. Existing hash-callback setups depend on provider-specific behavior. Interactive and silent callback URLs must be different.\n\n### Next.js\n\nKeep this browser library behind a client-only boundary: do not access `window` or initialize the OIDC client while rendering on the server. In the App Router, `'use client'` alone does not disable prerendering; use an appropriate client-only mounting or dynamic-import strategy.\n\nThe repository's [Next.js demo](../../examples/nextjs-demo/README.md) uses the **Pages Router** and a custom history adapter. For an initialized client-only provider using `next/router`, a post-login navigation adapter can look like this:\n\n```tsx\nimport { useRouter } from 'next/router';\nimport { OidcProvider } from '@axa-fr/react-oidc';\n\nfunction ClientAuth({ children }: React.PropsWithChildren): React.JSX.Element {\n const router = useRouter();\n\n return (\n => {\n await router.replace(path);\n window.dispatchEvent(new Event('popstate'));\n }}\n >\n {children}\n \n );\n}\n```\n\nHere `configuration` is your browser-side OIDC configuration. Do not copy `next/router` into an App Router application; adapt to that router's APIs and navigation lifecycle. This package does not provide server-side route protection or a server session.\n\n## Named configurations\n\nUse names to separate identity providers or sessions with different scopes. Give each configuration distinct callback URLs and, for worker mode, a matching trusted-domain entry.\n\n```tsx\n\n \n \n \n\n```\n\nSelect the name explicitly; nesting does not change the hooks' default name:\n\n```tsx\nconst { login, isAuthenticated } = useOidc('payments');\nconst { fetch: paymentsFetch } = useOidcFetch(undefined, 'payments');\n```\n\nUse `` for that session's protected UI. Token and user hooks also accept a configuration name.\n\n## Errors and missing providers\n\n`OidcError`, `OidcErrorCode`, `isOidcError`, `OidcStateError`, `OidcStateErrorCode`, `isOidcStateError`, and the PAR error classes/guards are re-exported from this package. Use stable codes and phases, not string matching, for error handling.\n\nSee the [core errors and events guide](../oidc-client/README.md#errors-and-events) for renewal errors, missing/mismatched state, missing nonces, retryability, and recovery. The provider's custom error/session-loss screens and `onEvent` callback are the React integration points. For strict renewal outside a hook, use `OidcClient.getOrThrow(name).renewTokensOrThrowAsync()`.\n\nWhen no client has been initialized for a name, `useOidc`, `useOidcUser`, `useOidcAccessToken`, and `useOidcIdToken` warn once per name and return unauthenticated/null defaults. This is useful in tests and Storybook, but does not initialize authentication.\n\n`OidcClient.get(name)` returns `null` for a missing client; `getOrThrow(name)` fails explicitly. `OidcSecure` and requests made through `useOidcFetch` require initialization and remain fail-fast. Mount a matching provider before using them.\n\n## Examples and further reading\n\n- [React demo](../../examples/react-oidc-demo/README.md) — routes, hooks, worker options, and named configurations.\n- [Next.js demo](../../examples/nextjs-demo/README.md) — Pages Router integration.\n- [Core client guide and API](../oidc-client/README.md).\n- [Service-worker protocol](../oidc-client-service-worker/PROTOCOL.md).\n- [Service-worker package guide](../oidc-client-service-worker/README.md).\n- [FAQ and deployment guidance](../../FAQ.md).\n\nThe demos use the repository's pnpm workspace. Follow their READMEs for setup rather than installing each package separately.\n","readmeFilename":"README.md"}