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.
HealthKit respects user preferences for units (metric vs imperial, etc.). Use getPreferredUnits to retrieve the user’s preferred units for displaying data.
Get preferred units
getPreferredUnits
Retrieve the user’s preferred units for one or more quantity types.
function getPreferredUnits(
identifiers: readonly QuantityTypeIdentifier[],
forceUpdate?: boolean
): Promise<IdentifierWithUnit[]>
identifiers
QuantityTypeIdentifier[]
required
Array of quantity type identifiers to get preferred units for
If true, bypass cache and fetch fresh units from HealthKit
Promise<IdentifierWithUnit[]> - Array of objects containing identifier and preferred unit
import { getPreferredUnits } from '@kingstinct/react-native-healthkit';
const units = await getPreferredUnits([
'HKQuantityTypeIdentifierHeight',
'HKQuantityTypeIdentifierBodyMass',
'HKQuantityTypeIdentifierDistanceWalkingRunning',
]);
console.log(units);
// [
// { identifier: 'HKQuantityTypeIdentifierHeight', unit: 'cm' },
// { identifier: 'HKQuantityTypeIdentifierBodyMass', unit: 'kg' },
// { identifier: 'HKQuantityTypeIdentifierDistanceWalkingRunning', unit: 'km' },
// ]
Display data with preferred units
Always display health data using the user’s preferred units:
import {
getMostRecentQuantitySample,
getPreferredUnits,
} from '@kingstinct/react-native-healthkit';
// Get user's preferred unit for height
const [{ unit }] = await getPreferredUnits(['HKQuantityTypeIdentifierHeight']);
// Query height in the preferred unit
const height = await getMostRecentQuantitySample(
'HKQuantityTypeIdentifierHeight',
unit
);
console.log(`Height: ${height.quantity} ${height.unit}`);
// US user: "Height: 70 in"
// EU user: "Height: 178 cm"
Caching
Preferred units are cached automatically for performance. Use forceUpdate to refresh:
// First call fetches from HealthKit and caches
const units1 = await getPreferredUnits(['HKQuantityTypeIdentifierBodyMass']);
// Subsequent calls use cached value
const units2 = await getPreferredUnits(['HKQuantityTypeIdentifierBodyMass']);
// Force a fresh fetch from HealthKit
const units3 = await getPreferredUnits(
['HKQuantityTypeIdentifierBodyMass'],
true
);
Cache preferred units at app startup and reuse them throughout your app’s
session. Only force update if the user explicitly changes their system
settings.
Common preferred units
Users in different regions typically prefer different units:
| Measurement | US Preferred | Metric Preferred |
|---|
| Height | in (inches) | cm (centimeters) |
| Weight | lb (pounds) | kg (kilograms) |
| Distance | mi (miles) | km (kilometers) |
| Temperature | degF (Fahrenheit) | degC (Celsius) |
| Energy | kcal (kilocalories) | kJ (kilojoules) |
Helper function
For convenience when querying a single type:
import { getPreferredUnit } from '@kingstinct/react-native-healthkit';
// Helper function for single identifier (exported by library)
const unit = await getPreferredUnit('HKQuantityTypeIdentifierBodyMass');
console.log(unit); // "kg" or "lb"
Automatic unit conversion
HealthKit automatically converts between units. You can request data in any compatible unit:
import { queryQuantitySamples } from '@kingstinct/react-native-healthkit';
// Request height in inches, even if stored in cm
const { samples } = await queryQuantitySamples(
'HKQuantityTypeIdentifierHeight',
{
unit: 'in',
limit: 1,
}
);
console.log(samples[0].quantity); // Automatically converted to inches
If you don’t specify a unit, HealthKit uses the user’s preferred unit
automatically.
Best practices
- Always respect user preferences - Display data in the user’s preferred units
- Cache units - Fetch once at app startup, reuse throughout session
- Handle undefined - Some quantity types may not have a preferred unit
- Batch requests - Request multiple units at once for better performance
// ✅ Good: Batch request
const units = await getPreferredUnits([
'HKQuantityTypeIdentifierHeight',
'HKQuantityTypeIdentifierBodyMass',
'HKQuantityTypeIdentifierStepCount',
]);
// ❌ Bad: Individual requests
const heightUnit = await getPreferredUnits(['HKQuantityTypeIdentifierHeight']);
const weightUnit = await getPreferredUnits(['HKQuantityTypeIdentifierBodyMass']);
const stepsUnit = await getPreferredUnits(['HKQuantityTypeIdentifierStepCount']);