expo-screen-time

The Screen Time API for React Native.

Block apps, run schedules and draw the shield on iOS and Android from one TypeScript API. Built for Expo. If you ship a focus, wellbeing or parental‑control app, this is the native layer.

$ npx expo install expo-screen-time
Requires Expo SDK 54+, iOS 16+ and Android 7+. MIT licensed.
9:41
FocusScreen.tsx● running
Same code, running on both phones.

A schedule is one call. It keeps running when your app is closed.

iOS enforces it from a DeviceActivity extension the config plugin generates. Android runs it in the module’s own service. Your code is the same.

00061218
07:30
free
schedule.ts
await ExpoScreenTime.startMonitoring({
activityName: 'workHours', // one name per schedule
selectionId: 'distractions',
schedule: {
// local time, can cross midnight
intervalStart: { hour: 9, minute: 0 },
intervalEnd: { hour: 17, minute: 0 },
repeats: true,
},
weekdays: [2, 3, 4, 5, 6], // Monday to Friday
});
useMonitorEvents((event) => console.log(event.eventType));

The rest is a few lines each.

shield.tsiOS · Android

Your words on the block screen, and what each button does.

ExpoScreenTime.setShieldConfig({
title: { text: 'Time to focus' },
subtitle: { text: 'This app is blocked during focus time.' },
primaryButton: { text: 'Close' },
secondaryButton: { text: 'Snooze 5 min' },
});
ExpoScreenTime.setShieldActions({
primaryAction: 'close',
secondaryAction: { type: 'snooze', duration: 5 * 60 },
});

The same day, on two systems.

On iOS the OS holds the shield. On Android the module’s engine does, and a user can stop it from Settings. When that happens, you are told exactly when.

ios
android
↑ 14:05–14:40
0006121824
Shield in force (work hours schedule)Not enforced: the user stopped the engine from Android Settings. iOS has no such switch.
await ExpoScreenTime.getEnforcementGaps() // [{ from: …14:05, to: …14:40, reason: 'stoppedByUser' }]

No Xcode surgery

The config plugin generates the four Screen Time extensions at prebuild. Re-running prebuild changes nothing.

Private by construction

Selections stay native. Your JavaScript holds an ID and opaque handles, never the apps someone picked.

Honest on Android

Capabilities tell you what each device enforces, and every gap in enforcement is reported.