Skip to main content

useSaveMeasurement

Use useSaveMeasurement() when a React component needs to submit a typed health measurement through the client supplied by OvokProvider.

Before you use it​

The component must be below OvokProvider and run on the client side. The hook reads the configured client from React context.

Arguments​

useSaveMeasurement() takes no arguments. It returns a save function for the component to call when the user or workflow is ready to submit a measurement.

Save input​

The returned function accepts one measurement request:

FieldRequiredWhat it describes
measurementYesThe typed measurement to convert and save.
deviceNoDevice details associated with the measurement.
effectiveDateTimeNoWhen the measurement took effect.
patientIdNoThe patient associated with the measurement.

The measurement’s type determines which values are meaningful. Use the measurement type definitions provided by the package for the data your device or workflow records.

Return value​

The save function returns a promise with one of two results:

StatusResultMeaning
savedresponseThe save completed and includes the server response.
queuedqueueIdOffline queueing retained the measurement for a later flush.

The SDK converts the typed input into FHIR Observation resources before submitting it. A queued result is pending; do not present it as confirmed by Ovok until the queue flush completes successfully.

Loading and errors​

This hook returns a save function, not a loading or error state. Track the promise in the component or the application workflow. Show a pending state while it is running and handle rejected requests at the call site.

The returned function is memoized against the client instance. Reuse the same client in the provider to avoid needlessly changing the function identity between renders.

Offline queue behavior​

Queueing is optional and disabled by default. When enabled, the client must have durable storage configured. A measurement that cannot be completed immediately may return queued; use flushOfflineMeasurementQueue() when the app resumes or connectivity returns, then update the UI from the flush result. See the offline measurement saves guide for the queue lifecycle, retry settings, and flush options.

When to use a different API​

Use OvokClient.saveMeasurement() directly from non-component code. For reading and mapping observations in a React component, use useObservations.

Example​

The save function is asynchronous. Handle both a completed save and a queued save in the component:

import { MeasurementTypeKey, useSaveMeasurement } from '@ovok/core';

export function SaveHeartRateButton() {
  const saveMeasurement = useSaveMeasurement();

  async function handleSave() {
    const result = await saveMeasurement({
      measurement: {
        measurementTypeKey: MeasurementTypeKey.heartRate,
        heartRate: 72,
      },
      effectiveDateTime: new Date(),
    });

    if (result.status === 'queued') {
      // Keep this reading in a pending state until the queue is flushed.
      return;
    }

    // The server has confirmed the save.
  }

  return <button onClick={() => void handleSave()}>Save reading</button>;
}