# React integration

Canonical page: https://docs.ovok.com/web-sdk/core/react

**Complexity:** 2 of 5 · **Client:** React (`@ovok/core/react`) · **Time:** about 10 minutes

## Provide the client [Client-side] [#provide-the-client-client-side]

Create the client from `@ovok/core` and pass it to `OvokProvider` from `@ovok/core/react`. Keep the client stable across renders.

```tsx title="app-providers.tsx"
'use client';

import { useState, type PropsWithChildren } from 'react';
import { Ovok } from '@ovok/core';
import { OvokProvider } from '@ovok/core/react';

export function AppProviders({ children }: PropsWithChildren) {
  const [client] = useState(() => new Ovok({
    baseUrl: 'https://api.sandbox.ovok.com',
    tenantCode: '{{TENANT_CODE}}',
  }));

  return <OvokProvider client={client}>{children}</OvokProvider>;
}
```

The React entry uses the host application's React installation.

## Read data with the hooks [Client-side] [#read-data-with-the-hooks-client-side]

Components below the provider can use the session and FHIR hooks.

```tsx title="patient-list.tsx"
'use client';

import { useSearch } from '@ovok/core/react';

export function PatientList() {
  const { data, loading, error, refetch } = useSearch('Patient', { _count: 10 });

  if (loading) return <p>Loading patients…</p>;
  if (error) return <button onClick={refetch}>Try again</button>;

  return <p>{data?.data.length ?? 0} patients</p>;
}
```

In server-rendered applications, create user-specific clients in the correct request scope and keep machine secrets on the server. The provider and hooks manage access to the client; they do not grant server authorization.

## Read the signed-in profile [Client-side] [#read-the-signed-in-profile-client-side]

`useProfile()` returns the signed-in profile reference, or `null` when signed out, in the same loading and error state as the other query hooks.

```tsx title="profile-name.tsx"
'use client';

import { useProfile } from '@ovok/core/react';

export function ProfileReference() {
  const { data: profile, loading } = useProfile();

  if (loading) return null;

  return <p>{profile ? profile.display ?? profile.reference : 'Signed out'}</p>;
}
```

## Show unsent measurements [Client-side] [#show-unsent-measurements-client-side]

`useOutbox()` returns what the [outbox](./namespaces/outbox.mdx) holds and updates as it changes. It is `undefined` until the first snapshot.

```tsx title="unsent-badge.tsx"
'use client';

import { useOutbox } from '@ovok/core/react';

export function UnsentBadge() {
  const outbox = useOutbox();

  if (!outbox || outbox.pending + outbox.rejected === 0) return null;

  return <p>{outbox.offline ? 'Offline: ' : ''}{outbox.pending} waiting, {outbox.rejected} need attention</p>;
}
```

## Test your integration [#test-your-integration]

1. Render `PatientList` inside `AppProviders` while signed in as a sandbox user.
2. Confirm that the loading text appears first and the patient count follows.

| Scenario | How to trigger it | Expected result |
| --- | --- | --- |
| The search succeeds | Sign in a sandbox user who can read patients | The patient count renders |
| The search fails | Point `baseUrl` at a host that does not answer | The "Try again" button renders |

## See also [#see-also]

- [React applications](./guides/react-applications.md)
- [API map](./api-surface.mdx)
- [API reference](./reference/index.mdx)
