useSubscribeToCategorySamples

React Hook for subscribing to category sample changes with automatic cleanup

Automatic subscription to category sample changes with React lifecycle management.

Hook signature

function useSubscribeToCategorySamples<TIdentifier extends CategoryTypeIdentifier>(
  identifier: TIdentifier,
  onChange: (args: OnCategorySamplesCallback<TIdentifier>) => void
): void

identifier · CategoryTypeIdentifier · required

The category type to subscribe to (e.g., 'HKCategoryTypeIdentifierSleepAnalysis')

onChange · OnCategorySamplesCallback · required

Callback function invoked when new category samples are available

Show OnCategorySamplesCallback properties

samples · CategorySample[]

Array of new category samples

deletedSamples · DeletedSample[]

Array of deleted samples (if applicable)

Usage

Subscribe to sleep analysis

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

function SleepTracker() {
  const [sleepSessions, setSleepSessions] = useState<CategorySample[]>([]);

  useSubscribeToCategorySamples(
    'HKCategoryTypeIdentifierSleepAnalysis',
    ({ samples }) => {
      setSleepSessions(prev => [...samples, ...prev]);
    }
  );

  return (
    <View>
      <Text>Recent Sleep Sessions: {sleepSessions.length}</Text>
    </View>
  );
}

Subscribe to mindful sessions

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

function MindfulnessTracker() {
  const [sessions, setSessions] = useState<number>(0);

  useSubscribeToCategorySamples(
    'HKCategoryTypeIdentifierMindfulSession',
    ({ samples }) => {
      setSessions(prev => prev + samples.length);
    }
  );

  return <Text>Mindfulness sessions today: {sessions}</Text>;
}

Handle deleted samples

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

function SymptomsLog() {
  const [symptoms, setSymptoms] = useState<CategorySample[]>([]);

  useSubscribeToCategorySamples(
    'HKCategoryTypeIdentifierAbdominalCramps',
    ({ samples, deletedSamples }) => {
      setSymptoms(prev => {
        // Remove deleted samples
        let updated = prev.filter(
          s => !deletedSamples.some(d => d.uuid === s.uuid)
        );
        // Add new samples
        return [...samples, ...updated];
      });
    }
  );

  return <Text>Logged symptoms: {symptoms.length}</Text>;
}

Features

• Automatic cleanup - Subscription is removed when component unmounts
• Stable callback - Uses ref to avoid re-subscribing on callback changes
• Type-safe - Full TypeScript support with category-specific types
• Deletion tracking - Receive notifications when samples are deleted
• Background updates - Works with background delivery when enabled

Notes

Request authorization before using this hook, otherwise your app will crash.

Use this hook for real-time updates. For one-time queries, use queryCategorySamples instead.

Related APIs

• useSubscribeToChanges - Generic change subscription
• useSubscribeToQuantitySamples - Quantity sample subscription
• subscribeToCategorySamples - Imperative subscription API
• enableBackgroundDelivery - Enable background updates