Integrating Apple HealthKit into React Native: A Step-by-Step Guide for Fitness Data

⚡ Quick Summary

• Configure iOS Permissions: Learn the exact Info.plist entries required for HealthKit.
• Master react-native-health: Initialize the library and handle authorization states.
• Fetch Real Data: Retrieve Step Counts and Sleep Analysis asynchronously.
• Data Normalization: How to transform raw Apple Health data into usable app state.

The "Quantified Self" movement is growing. Users expect their fitness apps to talk to each other, and on iOS, Apple Health is the central hub for this data. Whether you are building a workout tracker, a meditation app, or a medical dashboard, accessing HealthKit data can supercharge your user experience.

In this tutorial, we will build a React Native bridge to read Step Counts and Sleep Analysis data from the Apple Health repository. We will use the community-standard library react-native-health to handle the heavy lifting.

Prerequisites:

• React Native environment (CLI approach preferred for native linking)
• Xcode installed (Mac OS required for iOS development)
• An iOS Device or Simulator (Note: Simulators require manually adding health data to test)

Directly bridging Swift/Objective-C HealthKit APIs to JavaScript can be tedious. You have to handle:

1. Strict Privacy Rules: Apple will reject your app if permissions aren't handled perfectly.
2. Asynchronous Data: Health data queries can be heavy; blocking the JS thread is a no-go.
3. Complex Data Structures: HealthKit returns complex sample objects that need to be normalized for React state.

We will solve this by setting up a robust permission flow and a clean data service layer.

First, let's install the library. We are using react-native-health, which is the most maintained package for this purpose.

npm install react-native-health
# OR
yarn add react-native-health

Since this relies on native modules, we need to install the CocoaPods:

cd ios && pod install && cd ..

This is the step where most developers get stuck. Apple requires explicit declarations for why you want health data.

1. Enable Capabilities in Xcode

1. Open your project workspace (.xcworkspace) in Xcode.
2. Select your project target.
3. Go to the Signing & Capabilities tab.
4. Click + Capability.
5. Search for HealthKit and add it.

2. Update Info.plist

Open your ios/YourProjectName/Info.plist file. You must add two specific keys. If you omit these, your app will crash instantly upon requesting permissions.

<key>NSHealthShareUsageDescription</key>
<string>We need access to your health data to track your daily steps and sleep quality.</string>
<key>NSHealthUpdateUsageDescription</key>
<string>We need permission to save your workout sessions to Apple Health.</string>

”

Note: Even if you only read data, it is best practice (and sometimes required depending on the library version) to include the "Update" description to prevent binary rejection, though strictly speaking, "Share" is for reading and "Update" is for writing.

We need to initialize the library and request permissions from the user. Let's create a dedicated service file for this.

File: src/services/HealthKitService.js

import AppleHealthKit from 'react-native-health';

const permissions = {
  permissions: {
    read: [
      AppleHealthKit.Constants.Permissions.HeartRate,
      AppleHealthKit.Constants.Permissions.Steps,
      AppleHealthKit.Constants.Permissions.SleepAnalysis,
    ],
    write: [
      AppleHealthKit.Constants.Permissions.Steps,
    ],
  },
};

export const initHealthKit = () => {
  return new Promise((resolve, reject) => {
    AppleHealthKit.initHealthKit(permissions, (error) => {
      if (error) {
        console.log('[ERROR] Cannot grant permissions!');
        reject(error);
        return;
      }
      resolve(true);
    });
  });
};

How it works

The initHealthKit method triggers the native iOS modal asking the user to grant access. The permissions object defines exactly which metrics we want to read or write.

Now, let's implement the logic to fetch steps. Apple Health stores steps as "samples" (e.g., 50 steps at 2:00 PM, 100 steps at 2:15 PM). We usually want a daily aggregate.

Add this to src/services/HealthKitService.js:

export const getDailySteps = () => {
  return new Promise((resolve, reject) => {
    const options = {
      startDate: new Date(new Date().setHours(0, 0, 0, 0)).toISOString(), // Beginning of today
    };

    AppleHealthKit.getStepCount(options, (err, results) => {
      if (err) {
        reject(err);
        return;
      }
      // Result structure: { value: number, startDate: string, endDate: string }
      resolve(results.value);
    });
  });
};

Sleep data is more complex. HealthKit distinguishes between "In Bed", "Asleep", and "Awake".

Add this to src/services/HealthKitService.js:

export const getSleepData = () => {
  return new Promise((resolve, reject) => {
    const options = {
      startDate: new Date(new Date().setDate(new Date().getDate() - 7)).toISOString(), // Last 7 days
      endDate: new Date().toISOString(),
      limit: 10, // Optional limit
    };

    AppleHealthKit.getSleepSamples(options, (err, results) => {
      if (err) {
        reject(err);
        return;
      }
      
      // Filter only for 'ASLEEP' samples to get actual sleep time
      // Value '1' usually represents ASLEEP in HealthKit constants
      const deepSleepSamples = results.filter(sample => sample.value === 'ASLEEP');
      
      resolve(deepSleepSamples);
    });
  });
};

Let's build a simple React component to display this data.

File: src/App.js

import React, { useEffect, useState } from 'react';
import { View, Text, StyleSheet, Button, ActivityIndicator } from 'react-native';
import { initHealthKit, getDailySteps, getSleepData } from './services/HealthKitService';

const App = () => {
  const [steps, setSteps] = useState(0);
  const [sleepSamples, setSleepSamples] = useState([]);
  const [loading, setLoading] = useState(false);

  const fetchData = async () => {
    setLoading(true);
    try {
      // 1. Initialize Permissions
      await initHealthKit();

      // 2. Fetch Data in parallel
      const [stepCount, sleepData] = await Promise.all([
        getDailySteps(),
        getSleepData()
      ]);

      setSteps(stepCount);
      setSleepSamples(sleepData);
    } catch (error) {
      console.error('Error fetching health data:', error);
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    fetchData();
  }, []);

  return (
    <View style={styles.container}>
      <Text style={styles.header}>Health Dashboard 🍎</Text>
      
      {loading ? (
        <ActivityIndicator size="large" color="#0000ff" />
      ) : (
        <>
          <View style={styles.card}>
            <Text style={styles.label}>Steps Today</Text>
            <Text style={styles.value}>{Math.round(steps)}</Text>
          </View>

          <View style={styles.card}>
            <Text style={styles.label}>Sleep Sessions (Last 7 Days)</Text>
            <Text style={styles.value}>{sleepSamples.length} records found</Text>
          </View>

          <Button title="Refresh Data" onPress={fetchData} />
        </>
      )}
    </View>
  );
};

const styles = StyleSheet.create({
  container: { flex: 1, padding: 20, justifyContent: 'center', backgroundColor: '#f5f5f5' },
  header: { fontSize: 24, fontWeight: 'bold', marginBottom: 20, textAlign: 'center' },
  card: { backgroundColor: 'white', padding: 20, borderRadius: 10, marginBottom: 15, elevation: 3 },
  label: { fontSize: 16, color: '#666' },
  value: { fontSize: 28, fontWeight: 'bold', color: '#333' },
});

export default App;

1. Fail Gracefully: Users can deny permissions. Your app should check for this and show a UI explaining why the data is missing, rather than crashing or showing "0".
2. Minimal Scope: Only request permissions for data you actually use. Requesting everything looks suspicious to both users and Apple Reviewers.
3. Data Privacy: Never send HealthKit data to your servers without explicit consent in your privacy policy. Apple is extremely strict about this.

• Simulator Data: The iOS Simulator has no health data by default. You won't see any steps unless you open the "Health" app on the simulator and manually input data.
• Background Fetch: HealthKit queries can be slow. Avoid putting them in the render loop. Always use useEffect or a state management action.
• Android Support: react-native-health is iOS only. For Android, you need to use Google Fit (typically via react-native-google-fit) and build an abstraction layer to handle both platforms.

You've successfully bridged the gap between React Native and Apple HealthKit! By configuring the native permissions and implementing asynchronous fetch strategies, you can now build rich, data-driven fitness experiences.

The next step? Try visualizing this data using a charting library like react-native-svg-charts to give your users a visual representation of their progress.

Happy Coding! 🏃‍♂️

• react-native-health GitHub Repo
• Apple HealthKit Documentation
• Apple Human Interface Guidelines for Health

1. Have you faced rejection from the Apple App Store regarding HealthKit permissions? How did you solve it?
2. What strategy do you use to synchronize local HealthKit data with a backend database?
3. How would you handle the differences between Google Fit and Apple HealthKit in a cross-platform app?