apple-health

apple-health

An Expo module for interacting with Apple HealthKit on iOS devices. Read and write health data, subscribe to real-time updates, display activity rings, and more.

Features

• 70+ quantity types - Steps, heart rate, calories, distance, sleep, nutrition, and more
• 40+ category types - Sleep analysis, symptoms, mindfulness, reproductive health
• 80+ workout types - Running, cycling, swimming, yoga, and more
• React hooks - usePermissions, useHealthKitQuery, useHealthKitStatistics, useHealthKitSubscription, useHealthKitAnchor
• Fluent builders - HealthKitQuery and HealthKitSampleBuilder for imperative use
• Real-time subscriptions - Get notified when health data changes
• Background delivery - Process health updates when your app is in the background
• Activity rings - Native Apple Watch-style activity ring visualization
• Full TypeScript support - Complete typings for all APIs

Installation

npx expo install apple-health

Configuration

Add the config plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": [
      [
        "apple-health",
        {
          "healthSharePermission": "Allow $(PRODUCT_NAME) to read your health data",
          "healthUpdatePermission": "Allow $(PRODUCT_NAME) to write your health data",
          "backgroundDelivery": true
        }
      ]
    ]
  }
}

Plugin Options

Option	Type	Description
healthSharePermission	string	Custom message for read permission prompt
healthUpdatePermission	string	Custom message for write permission prompt
backgroundDelivery	boolean	Enable background delivery for health updates
isClinicalDataEnabled	boolean	Enable clinical records access (requires Apple approval)

Quick Start

import {
  usePermissions,
  useHealthKitQuery,
  useHealthKitStatistics,
  PermissionStatus,
} from "apple-health/hooks";

export default function App() {
  // Request authorization with Expo-style hook
  const [status, requestPermission] = usePermissions({
    read: ["stepCount", "heartRate", "sleepAnalysis"],
    write: ["stepCount"],
  });

  // Query samples with a hook
  const { data: heartRates } = useHealthKitQuery({
    type: "heartRate",
    kind: "quantity",
    limit: 10,
    skip: status?.status !== PermissionStatus.GRANTED,
  });

  // Get aggregated statistics
  const { data: steps } = useHealthKitStatistics({
    type: "stepCount",
    aggregations: ["cumulativeSum"],
    startDate: new Date(Date.now() - 24 * 60 * 60 * 1000),
    skip: status?.status !== PermissionStatus.GRANTED,
  });

  return (
    <View>
      <Button title="Authorize" onPress={requestPermission} />
      <Text>Status: {status?.status}</Text>
      <Text>Today's steps: {steps?.sumQuantity ?? 0}</Text>
    </View>
  );
}

Authorization

usePermissions Hook (Recommended)

The usePermissions hook follows Expo's permission pattern with automatic status fetching:

import { usePermissions, PermissionStatus } from "apple-health/hooks";

function App() {
  const [status, requestPermission, getPermission] = usePermissions({
    read: ["stepCount", "heartRate", "sleepAnalysis"],
    write: ["stepCount"],
  });

  if (status?.status === PermissionStatus.GRANTED) {
    return <Text>Access granted!</Text>;
  }

  return <Button title="Grant Access" onPress={requestPermission} />;
}

Hook options:

Option	Type	Description
read	string[]	Data types to request read access for
write	string[]	Data types to request write access for
get	boolean	Auto-fetch status on mount (default: true)
request	boolean	Auto-request on mount (default: false)

Return value: [status, requestPermission, getPermission]

• status - Current permission status (HealthKitPermissionResponse | null)
• requestPermission - Function to request permissions
• getPermission - Function to refresh current status

Status properties:

Property	Type	Description
status	PermissionStatus	'granted', 'denied', or 'undetermined'
granted	boolean	Whether all permissions are granted
canAskAgain	boolean	Whether the user can be prompted
expires	'never'	Permissions don't expire
permissions	object	Detailed per-type authorization status

Imperative API

For non-React contexts, use the module directly:

import AppleHealth from "apple-health";

const result = await AppleHealth.requestAuthorization({
  read: ["stepCount", "heartRate", "sleepAnalysis"],
  write: ["stepCount"],
});

console.log(result.status); // 'notDetermined' | 'sharingDenied' | 'sharingAuthorized'

Or use the standalone async functions:

import { getPermissionsAsync, requestPermissionsAsync } from "apple-health/hooks";

// Check current status
const status = await getPermissionsAsync({
  read: ["stepCount"],
  write: ["stepCount"],
});

// Request permissions
const result = await requestPermissionsAsync({
  read: ["stepCount", "heartRate"],
  write: ["stepCount"],
});

Important: HealthKit intentionally hides read authorization status for privacy. The granted and status properties only reflect write permissions. For read-only access, the status will always be undetermined. To verify read access, try querying data directly.

React Hooks

usePermissions

Request and check HealthKit authorization using Expo's permission pattern:

import { usePermissions, PermissionStatus } from "apple-health/hooks";

const [status, requestPermission, getPermission] = usePermissions({
  read: ["stepCount", "heartRate"],
  write: ["stepCount"],
  // get: true,    // Auto-fetch on mount (default)
  // request: false, // Auto-request on mount
});

// Check status (reflects write permissions only)
if (status?.granted) {
  // Write permissions granted
}

// Request permissions
await requestPermission();

// Refresh status
await getPermission();

Note: HealthKit hides read permission status for privacy. The granted property only reflects write permissions. For read-only apps, query data directly to verify access.

useHealthKitQuery

Fetch health samples with automatic lifecycle management:

import { useHealthKitQuery } from "apple-health/hooks";

const {
  data, // HealthKitSample[] | null
  isLoading,
  error,
  refetch,
  deleteSample,
} = useHealthKitQuery({
  type: "heartRate",
  kind: "quantity", // 'quantity' | 'category' | 'workout'
  limit: 10,
  ascending: false,
  startDate: new Date("2024-01-01"),
  endDate: new Date(),
  skip: !authorized, // Skip query until authorized
});

// Samples have a delete() method
const handleDelete = async (sample) => {
  await deleteSample(sample);
};

useHealthKitStatistics

Get aggregated statistics for quantity types:

import { useHealthKitStatistics } from "apple-health/hooks";

// Single aggregated result
const { data: todaySteps } = useHealthKitStatistics({
  type: "stepCount",
  aggregations: ["cumulativeSum"],
  startDate: todayStart,
  endDate: new Date(),
});
// data.sumQuantity = 8500

// Time-bucketed results (returns array)
const { data: weeklySteps } = useHealthKitStatistics({
  type: "stepCount",
  aggregations: ["cumulativeSum"],
  interval: "day", // 'hour' | 'day' | 'week' | 'month' | 'year'
  startDate: weekAgo,
  endDate: new Date(),
});
// data = [{ startDate, endDate, sumQuantity }, ...]

Aggregation types:

• cumulativeSum - Total sum (steps, calories, distance)
• discreteAverage - Average value (heart rate, temperature)
• discreteMin - Minimum value
• discreteMax - Maximum value
• mostRecent - Most recent value

useHealthKitSubscription

Get notified when HealthKit data changes:

import { useHealthKitSubscription } from "apple-health/hooks";

const { isActive, lastUpdate, start, pause, resume, unsubscribe } =
  useHealthKitSubscription({
    type: "stepCount",
    onUpdate: () => {
      // Data changed - refetch your queries
      refetchSteps();
    },
    autoStart: true,
  });

useHealthKitAnchor

Paginated incremental sync for large datasets:

import { useHealthKitAnchor } from "apple-health/hooks";

const {
  samples, // All fetched samples
  deletedObjects, // Tracked deletions for sync
  hasMore,
  isLoading,
  fetchMore,
  reset,
  getAnchorState, // Serialize for persistence
} = useHealthKitAnchor({
  type: "stepCount",
  kind: "quantity",
  limit: 50, // Fetch 50 at a time
  persistenceKey: "stepCount-anchor", // Auto-persist anchor state
});

// Load more samples
<Button
  title={`Load More (${samples.length} loaded)`}
  onPress={fetchMore}
  disabled={!hasMore}
/>;

Imperative API

HealthKitQuery

Fluent query builder for one-off queries:

import { HealthKitQuery } from "apple-health";

const samples = await new HealthKitQuery()
  .type("sleepAnalysis", "category")
  .dateRange(yesterday, today)
  .limit(10)
  .ascending(false)
  .execute();

// Get statistics
const stats = await new HealthKitQuery()
  .type("stepCount", "quantity")
  .dateRange(weekAgo, today)
  .aggregations(["cumulativeSum", "discreteAverage"])
  .executeStatistics();

// Time-bucketed statistics
const dailyStats = await new HealthKitQuery()
  .type("heartRate", "quantity")
  .dateRange(weekAgo, today)
  .interval("day")
  .aggregations(["discreteAverage", "discreteMin", "discreteMax"])
  .executeStatistics();

HealthKitSampleBuilder

Create and save health samples:

import { HealthKitSampleBuilder } from "apple-health";

// Save a quantity sample
const stepsSample = await new HealthKitSampleBuilder()
  .quantityType("stepCount")
  .value(1000)
  .unit("count")
  .startDate(hourAgo)
  .endDate(new Date())
  .save();

// Save a category sample
const sleepSample = await new HealthKitSampleBuilder()
  .categoryType("sleepAnalysis")
  .categoryValue(4) // 4 = deep sleep
  .startDate(lastNight)
  .endDate(thisMonring)
  .save();

// Save a workout
const workoutSample = await new HealthKitSampleBuilder()
  .workoutType("running")
  .startDate(thirtyMinutesAgo)
  .endDate(new Date())
  .totalEnergyBurned(250) // kcal
  .totalDistance(5000) // meters
  .metadata({ HKIndoorWorkout: false })
  .save();

Subscriptions & Anchors

HealthKitSubscription

Low-level subscription for real-time updates:

import { HealthKitSubscription } from "apple-health";

const subscription = new HealthKitSubscription("stepCount");

subscription.onUpdate = () => {
  console.log("Step count changed!");
};

subscription.start();
// ... later
subscription.unsubscribe();

HealthKitAnchor

Paginated sync with deletion tracking:

import { HealthKitAnchor } from "apple-health";

const anchor = new HealthKitAnchor("stepCount", "quantity");

// Restore previous anchor state
const savedState = await AsyncStorage.getItem("anchor-state");
if (savedState) anchor.restore(savedState);

// Fetch samples
const { samples, deletedObjects, hasMore } = await anchor.fetchNext(50);

// Process deletions for sync
for (const deleted of deletedObjects) {
  await localDB.delete(deleted.uuid);
}

// Save anchor state for next session
await AsyncStorage.setItem("anchor-state", anchor.serialize());

Background Delivery

Receive health updates when your app is in the background:

import AppleHealth from "apple-health";
import { useEvent } from "expo";

// Enable background delivery (once per type)
await AppleHealth.enableBackgroundDelivery("stepCount", "hourly");
// frequency: 'immediate' | 'hourly' | 'daily'

// Listen for background updates
const event = useEvent(AppleHealth, "onBackgroundDelivery");
useEffect(() => {
  if (event) {
    console.log("Background update:", event.typeIdentifier);
  }
}, [event]);

// Disable when no longer needed
await AppleHealth.disableBackgroundDelivery("stepCount");
await AppleHealth.disableAllBackgroundDelivery();

Activity Rings

Display Apple Watch-style activity rings:

import { ActivityRingView } from "apple-health";
import AppleHealth from "apple-health";

// Fetch today's activity summary
const summaries = await AppleHealth.queryActivitySummary(
  today.toISOString(),
  today.toISOString()
);

<ActivityRingView
  summary={{
    activeEnergyBurned: 420,
    activeEnergyBurnedGoal: 500,
    appleExerciseTime: 25,
    appleExerciseTimeGoal: 30,
    appleStandHours: 10,
    appleStandHoursGoal: 12,
  }}
  style={{ width: 150, height: 150 }}
/>;

User Characteristics

Read user profile data (requires authorization):

import AppleHealth from "apple-health";

const dateOfBirth = await AppleHealth.getDateOfBirth();
const biologicalSex = await AppleHealth.getBiologicalSex();
const bloodType = await AppleHealth.getBloodType();
const skinType = await AppleHealth.getFitzpatrickSkinType();
const wheelchairUse = await AppleHealth.getWheelchairUse();

Deleting Samples

Delete samples you've written:

// Delete via sample object
await sample.delete();

// Delete via hook
const { deleteSample } = useHealthKitQuery({
  type: "stepCount",
  kind: "quantity",
});
await deleteSample(sample);

// Delete by date range
await AppleHealth.deleteSamples(
  "stepCount",
  startDate.toISOString(),
  endDate.toISOString()
);

Data Types

Quantity Types

Category	Types
Body	bodyMass, height, bodyFatPercentage, bodyMassIndex, leanBodyMass, waistCircumference
Fitness	stepCount, distanceWalkingRunning, distanceCycling, activeEnergyBurned, basalEnergyBurned, flightsClimbed, appleExerciseTime, vo2Max
Vitals	heartRate, restingHeartRate, walkingHeartRateAverage, heartRateVariabilitySDNN, bloodPressureSystolic, bloodPressureDiastolic, oxygenSaturation, respiratoryRate, bodyTemperature
Nutrition	dietaryEnergyConsumed, dietaryProtein, dietaryCarbohydrates, dietaryFatTotal, dietaryCaffeine, dietaryWater

Category Types

Category	Types
Sleep	sleepAnalysis
Activity	appleStandHour, lowCardioFitnessEvent
Heart	highHeartRateEvent, lowHeartRateEvent, irregularHeartRhythmEvent
Symptoms	headache, fatigue, fever, nausea, dizziness, shortnessOfBreath
Mindfulness	mindfulSession
Reproductive Health	menstrualFlow*, cervicalMucusQuality, ovulationTestResult, sexualActivity

* menstrualFlow requires the HKMenstrualCycleStart metadata key (boolean). See Required Metadata.

Sleep Values

Value	Meaning
0	In Bed
2	Awake
3	Core Sleep (light)
4	Deep Sleep
5	REM Sleep

Symptom Values

Value	Meaning
0	Not Present
1	Mild
2	Moderate
3	Severe

Required Metadata

Some category types require specific metadata keys to be set. If metadata is missing, HealthKit will reject the sample with a validation error.

Type	Required Metadata Key	Type	Description
menstrualFlow	HKMenstrualCycleStart	boolean	true if this sample starts a new menstrual cycle

Example:

await new HealthKitSampleBuilder()
  .categoryType("menstrualFlow")
  .categoryValue(2) // light flow
  .startDate(startOfDay)
  .endDate(endOfDay)
  .metadata({ HKMenstrualCycleStart: true }) // Required!
  .save();

TypeScript Types

import type {
  // Data type identifiers
  QuantityTypeIdentifier,
  CategoryTypeIdentifier,
  CharacteristicTypeIdentifier,
  WorkoutActivityType,
  HealthKitDataType,

  // Sample types
  QuantitySample,
  CategorySample,
  WorkoutSample,
  HealthKitSample,

  // Query/statistics
  StatisticsResult,
  StatisticsAggregation,
  ActivitySummary,

  // Authorization
  HealthKitPermissions,
  AuthorizationResult,
  AuthorizationStatus,

  // Permissions (Expo-style)
  HealthKitPermissionOptions,
  HealthKitPermissionResponse,
} from "apple-health";

// PermissionStatus enum
import { PermissionStatus } from "apple-health";
// PermissionStatus.GRANTED | PermissionStatus.DENIED | PermissionStatus.UNDETERMINED

CLI & DevTools

This package includes a CLI for querying and writing HealthKit data during development.

Quick Start

• Enable devtools in your app:

  import { useHealthKitDevTools } from "apple-health/dev-tools";
  
  export default function App() {
    useHealthKitDevTools();
    return <YourApp />;
  }
  

• Run CLI commands:

  # Check connection
  bunx apple-health status
  
  # Write data with natural date formats
  bunx apple-health write quantity heartRate 72 --start "today 8am"
  bunx apple-health write quantity stepCount 8000 --start "yesterday" --duration "1d"
  
  # Query data
  bunx apple-health query quantity heartRate --limit 10
  
  # Get statistics
  bunx apple-health stats stepCount --interval day --start "-7d"
  
  # Interactive mode
  bunx apple-health repl
  

Documentation

• CLI Reference - Complete command reference, date formats, batch mode
• Seeding Data Guide - Using Claude Code to generate test data

Notes

• iOS only - HealthKit is not available on Android
• Simulator limitations - The iOS Simulator has limited HealthKit data; use a real device for full testing
• Privacy - HealthKit hides read authorization status; query data to verify access
• iOS 16+ types - Some types (e.g., runningPower, underwaterDepth) require iOS 16+

Contributing

Contributions are very welcome! Please refer to guidelines described in the contributing guide.