@iehr/react-hooks

iEHR React Hooks Library

The iEHR React Hooks Library provides non-UI React features for your application.

Most users will want the full iEHR React Component Library, @iehr/react. However, that library has peer dependencies on Mantine, which may not be desired.

Key Features

• useIEHR - handles shared global instance of IEHRClient
• useResource - reads a resource by ID or reference with intelligent caching
• useSearch - performs a FHIR search with intelligent state management
• useSubscription - subscribes to a FHIR search criteria and calls a given callback upon receiving a relevant notification

Installation

Add as a dependency:

npm install @iehr/react-hooks

Note the following peer dependencies:

• @iehr/core
• react
• react-dom

Setup

import { IEHRClient } from '@iehr/core';
import { IEHRProvider } from '@iehr/react';

const iehr = new IEHRClient();

export function App() {
  return (
    <IEHRProvider iehr={iehr}>
      <MyPage1 />
      <MyPage2 />
      <Etc />
    </IEHRProvider>
  );
}

For more details on how to setup IEHRClient, refer to the docs for iehr.

useIEHR

import { useIEHR } from '@iehr/react-hooks';

export function MyComponent() {
  const iehr = useIEHR();
  return <div>{JSON.stringify(iehr.getProfile())}</div>;
}

useIEHRContext

useIEHRContext can be used to access the IEHRContext provided by the IEHRProvider directly. The IEHRContext has the following interface:

interface IEHRContext {
  iehr: IEHRClient;
  navigate: IEHRNavigateFunction;
  profile?: ProfileResource;
  loading: boolean;
}

Using loading to know when IEHRClient initialization is done

You can use the loading property from useIEHRContext() to know when IEHRClient has finished initialization successfully. loading is updated asynchronously so it will usually start as false and change to true once the client has finished its initialization.

function MyComponent(): JSX.Element {
  const { loading } = useIEHRContext();
  return loading ? <Spinner /> : <div>Loaded!</div>;
}

useSubscription

useSubscription creates an in-memory Subscription resource with the given criteria on the iEHR server and calls the given callback when an event notification is triggered by a resource interaction over a WebSocket connection.

Subscriptions created with this hook are lightweight, share a single WebSocket connection, and are automatically untracked and cleaned up when the containing component is no longer mounted.

function MyComponent(): JSX.Element {
  const [notificationCount, setNotificationCount] = useState(0);

  useSubscription('Communication?sender=Practitioner/abc-123&recipient=Practitioner/me-456', (bundle: Bundle) => {
    console.log('Received a message from Practitioner/abc-123!');
    handleNotificationBundle(bundle); // Do something with the bundle
    setNotificationCount((s) => s + 1);
  });

  return <div>Notifications received: {notificationCount}</div>;
}

See also: useSubscription docs

Usage within Expo app

Usage within Expo / React Native has some special considerations. See: @iehr/expo-polyfills README

About iEHR

iEHR is a FHIR®-native, AI-infused, API-first, interoperable EHR. iEHR makes it easy to build healthcare apps quickly with less code.

License

Apache 2.0.

Copyright © Medplum 2025 (HL7® FHIR® US)

Copyright © iEHR.ai 2025 (HL7® FHIR® International, AI & Data platform)