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.

​
Overview

The useStatisticsForQuantity hook fetches statistical data (sum, average, min, max, etc.) for a quantity type over a specified date range and automatically subscribes to updates.

​
Usage

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

const statistics = useStatisticsForQuantity(
  'HKQuantityTypeIdentifierStepCount',
  ['cumulativeSum'],
  new Date('2024-01-01'),
  new Date()
);

​
Parameters

​
identifier
QuantityTypeIdentifier
required
The HealthKit quantity type identifier
​
options
StatisticsOptions[]
required
Array of statistical options to computeAvailable options:
  • cumulativeSum - Total sum of all samples
  • discreteAverage - Average of discrete samples
  • discreteMax - Maximum value
  • discreteMin - Minimum value
  • duration - Total duration
  • mostRecent - Most recent value
  • separateBySource - Separate statistics by source
​
from
Date
required
Start date for the statistics query
​
to
Date
End date for the statistics query. Defaults to current date if not provided.
​
unit
string
Unit for the quantity. Defaults to the user’s preferred unit.

​
Return Value

​
statistics
QueryStatisticsResponse | null
Statistics result or null if loading/unavailable.
interface QueryStatisticsResponse {
  averageQuantity?: number;
  maximumQuantity?: number;
  minimumQuantity?: number;
  sumQuantity?: number;
  mostRecentQuantity?: number;
  duration?: number;
}

​
Example: Daily Steps

import { useStatisticsForQuantity } from '@kingstinct/react-native-healthkit';
import { View, Text } from 'react-native';

function DailySteps() {
  const today = new Date();
  today.setHours(0, 0, 0, 0);
  
  const stats = useStatisticsForQuantity(
    'HKQuantityTypeIdentifierStepCount',
    ['cumulativeSum'],
    today,
    new Date()
  );

  if (!stats) {
    return <Text>Loading steps...</Text>;
  }

  return (
    <View>
      <Text style={{ fontSize: 32, fontWeight: 'bold' }}>
        {stats.sumQuantity?.toLocaleString() || 0}
      </Text>
      <Text style={{ color: 'gray' }}>steps today</Text>
    </View>
  );
}

​
Example: Heart Rate Statistics

import { useStatisticsForQuantity } from '@kingstinct/react-native-healthkit';
import { View, Text, StyleSheet } from 'react-native';

function HeartRateStats() {
  const startOfDay = new Date();
  startOfDay.setHours(0, 0, 0, 0);
  
  const stats = useStatisticsForQuantity(
    'HKQuantityTypeIdentifierHeartRate',
    ['discreteAverage', 'discreteMin', 'discreteMax'],
    startOfDay,
    new Date(),
    'count/min'
  );

  if (!stats) {
    return <Text>Loading heart rate data...</Text>;
  }

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Heart Rate Today</Text>
      
      <View style={styles.statsRow}>
        <View style={styles.stat}>
          <Text style={styles.label}>Average</Text>
          <Text style={styles.value}>
            {stats.averageQuantity?.toFixed(0) || '--'}
          </Text>
          <Text style={styles.unit}>BPM</Text>
        </View>
        
        <View style={styles.stat}>
          <Text style={styles.label}>Min</Text>
          <Text style={styles.value}>
            {stats.minimumQuantity?.toFixed(0) || '--'}
          </Text>
          <Text style={styles.unit}>BPM</Text>
        </View>
        
        <View style={styles.stat}>
          <Text style={styles.label}>Max</Text>
          <Text style={styles.value}>
            {stats.maximumQuantity?.toFixed(0) || '--'}
          </Text>
          <Text style={styles.unit}>BPM</Text>
        </View>
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    padding: 20,
    backgroundColor: '#fff',
    borderRadius: 12,
  },
  title: {
    fontSize: 18,
    fontWeight: 'bold',
    marginBottom: 15,
  },
  statsRow: {
    flexDirection: 'row',
    justifyContent: 'space-around',
  },
  stat: {
    alignItems: 'center',
  },
  label: {
    fontSize: 12,
    color: '#999',
    marginBottom: 5,
  },
  value: {
    fontSize: 24,
    fontWeight: 'bold',
  },
  unit: {
    fontSize: 12,
    color: '#666',
    marginTop: 2,
  },
});

​
Example: Weekly Activity Summary

import { useStatisticsForQuantity } from '@kingstinct/react-native-healthkit';
import { View, Text } from 'react-native';

function WeeklyActivity() {
  const weekAgo = new Date();
  weekAgo.setDate(weekAgo.getDate() - 7);
  
  const steps = useStatisticsForQuantity(
    'HKQuantityTypeIdentifierStepCount',
    ['cumulativeSum', 'discreteAverage'],
    weekAgo,
    new Date()
  );
  
  const calories = useStatisticsForQuantity(
    'HKQuantityTypeIdentifierActiveEnergyBurned',
    ['cumulativeSum'],
    weekAgo,
    new Date(),
    'kcal'
  );
  
  const distance = useStatisticsForQuantity(
    'HKQuantityTypeIdentifierDistanceWalkingRunning',
    ['cumulativeSum'],
    weekAgo,
    new Date(),
    'km'
  );

  if (!steps || !calories || !distance) {
    return <Text>Loading weekly data...</Text>;
  }

  return (
    <View style={{ padding: 20, backgroundColor: '#f5f5f5', borderRadius: 12 }}>
      <Text style={{ fontSize: 20, fontWeight: 'bold', marginBottom: 15 }}>
        Last 7 Days
      </Text>
      
      <View style={{ gap: 10 }}>
        <View>
          <Text style={{ fontSize: 14, color: '#666' }}>Total Steps</Text>
          <Text style={{ fontSize: 24, fontWeight: 'bold' }}>
            {steps.sumQuantity?.toLocaleString()}
          </Text>
          <Text style={{ fontSize: 12, color: '#999' }}>
            Avg: {steps.averageQuantity?.toFixed(0)}/day
          </Text>
        </View>
        
        <View>
          <Text style={{ fontSize: 14, color: '#666' }}>Calories Burned</Text>
          <Text style={{ fontSize: 24, fontWeight: 'bold' }}>
            {calories.sumQuantity?.toFixed(0)} kcal
          </Text>
        </View>
        
        <View>
          <Text style={{ fontSize: 14, color: '#666' }}>Distance</Text>
          <Text style={{ fontSize: 24, fontWeight: 'bold' }}>
            {distance.sumQuantity?.toFixed(2)} km
          </Text>
        </View>
      </View>
    </View>
  );
}

​
Example: Custom Date Range

import { useStatisticsForQuantity } from '@kingstinct/react-native-healthkit';
import { useState } from 'react';
import { View, Text, Button } from 'react-native';

function CustomRangeStats() {
  const [startDate, setStartDate] = useState(new Date('2024-01-01'));
  const [endDate, setEndDate] = useState(new Date('2024-01-31'));
  
  const stats = useStatisticsForQuantity(
    'HKQuantityTypeIdentifierStepCount',
    ['cumulativeSum', 'discreteAverage', 'discreteMax'],
    startDate,
    endDate
  );

  const setThisMonth = () => {
    const now = new Date();
    setStartDate(new Date(now.getFullYear(), now.getMonth(), 1));
    setEndDate(new Date(now.getFullYear(), now.getMonth() + 1, 0));
  };

  const setLastMonth = () => {
    const now = new Date();
    setStartDate(new Date(now.getFullYear(), now.getMonth() - 1, 1));
    setEndDate(new Date(now.getFullYear(), now.getMonth(), 0));
  };

  return (
    <View style={{ padding: 20 }}>
      <View style={{ flexDirection: 'row', gap: 10, marginBottom: 20 }}>
        <Button title="This Month" onPress={setThisMonth} />
        <Button title="Last Month" onPress={setLastMonth} />
      </View>
      
      {stats ? (
        <View>
          <Text>Total: {stats.sumQuantity?.toLocaleString()}</Text>
          <Text>Average: {stats.averageQuantity?.toFixed(0)}/day</Text>
          <Text>Peak: {stats.maximumQuantity?.toLocaleString()}</Text>
        </View>
      ) : (
        <Text>Loading...</Text>
      )}
    </View>
  );
}

​
Auto-Updates

The hook automatically subscribes to changes for the specified quantity type. When new data is saved within the date range, the statistics will update.

​
Important Notes

Request authorization first. Ensure you’ve requested authorization for the quantity type before using this hook, or your app will crash.
For better performance with large date ranges, consider using queryStatisticsCollectionForQuantity to get statistics broken down by intervals (hourly, daily, etc.).

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us