Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/kingstinct/react-native-healthkit/llms.txt

Use this file to discover all available pages before exploring further.

​
saveQuantitySample

Save a new quantity sample to HealthKit. 
saveQuantitySample(
  identifier: QuantityTypeIdentifierWriteable,
  unit: string,
  value: number,
  start: Date,
  end: Date,
  metadata?: AnyMap
): Promise<QuantitySample | undefined>
​
identifier
QuantityTypeIdentifierWriteable
required
The quantity type identifier to save. Must be a writeable type (read-only types like 'HKQuantityTypeIdentifierAppleExerciseTime' cannot be written to)
​
unit
string
required
The unit of measurement for the quantity value (e.g., 'count', 'kg', 'mi', 'IU')
​
value
number
required
The numeric value of the quantity
​
start
Date
required
The start date and time for the sample
​
end
Date
required
The end date and time for the sample. For instantaneous measurements (like weight), this should typically be the same as the start date
​
metadata
AnyMap
Optional metadata to attach to the sample. Can include both built-in HealthKit metadata keys and custom app-specific data

​
Returns

​
sample
QuantitySample | undefined
The saved quantity sample, or undefined if the save failed

​
Examples

​
Save step count

import { saveQuantitySample } from '@kingstinct/react-native-healthkit'

const stepSample = await saveQuantitySample(
  'HKQuantityTypeIdentifierStepCount',
  'count',
  1000,
  new Date('2024-03-15T10:00:00'),
  new Date('2024-03-15T11:00:00')
)

if (stepSample) {
  console.log(`Saved ${stepSample.quantity} steps`)
}

​
Save weight measurement

import { saveQuantitySample } from '@kingstinct/react-native-healthkit'

const now = new Date()
const weightSample = await saveQuantitySample(
  'HKQuantityTypeIdentifierBodyMass',
  'kg',
  70.5,
  now,
  now, // Same as start for instantaneous measurements
  {
    HKWasUserEntered: true
  }
)

​
Save insulin delivery with metadata

import { 
  saveQuantitySample, 
  InsulinDeliveryReason 
} from '@kingstinct/react-native-healthkit'

const insulinSample = await saveQuantitySample(
  'HKQuantityTypeIdentifierInsulinDelivery',
  'IU',
  5.5,
  new Date(),
  new Date(),
  {
    HKInsulinDeliveryReason: InsulinDeliveryReason.bolus,
    notes: 'Pre-meal insulin'
  }
)

​
Save blood glucose with meal context

import { saveQuantitySample } from '@kingstinct/react-native-healthkit'

const glucoseSample = await saveQuantitySample(
  'HKQuantityTypeIdentifierBloodGlucose',
  'mg/dL',
  120,
  new Date(),
  new Date(),
  {
    HKBloodGlucoseMealTime: 1, // Preprandial (before meal)
    HKWasUserEntered: true
  }
)
Make sure you’ve requested write permission for the quantity type using requestAuthorization before calling saveQuantitySample, or the app will crash.
Some quantity types are read-only (like HKQuantityTypeIdentifierAppleExerciseTime) and cannot be saved by third-party apps. These are defined as QuantityTypeIdentifierReadOnly in the type system.

​
Metadata Keys

HealthKit metadata keys follow a specific naming pattern. In the Apple documentation, they appear with the HKMetadataKey prefix (e.g., HKMetadataKeyExternalUUID), but when serialized, they use the HK prefix (e.g., HKExternalUUID). Common metadata keys include:
  • HKExternalUUID - Unique identifier from external system
  • HKWasUserEntered - Boolean indicating manual entry
  • HKInsulinDeliveryReason - Reason for insulin delivery (basal/bolus)
  • HKBloodGlucoseMealTime - Timing relative to meals
  • HKHeartRateMotionContext - Motion context for heart rate
You can also use custom string keys for app-specific metadata.

​
Unit Compatibility

Use the isQuantityCompatibleWithUnit() helper function to check if a unit is compatible with a quantity type before saving: 
import { isQuantityCompatibleWithUnit } from '@kingstinct/react-native-healthkit'

const isCompatible = isQuantityCompatibleWithUnit(
  'HKQuantityTypeIdentifierBodyMass',
  'kg'
)

if (isCompatible) {
  await saveQuantitySample(
    'HKQuantityTypeIdentifierBodyMass',
    'kg',
    70.5,
    new Date(),
    new Date()
  )
}

Build docs developers (and LLMs) love

Get started for freeTalk to us