expo-screen-time

An Expo module that wraps Apple's Screen Time APIs (FamilyControls, ManagedSettings, DeviceActivity) for React Native. Enables parental control features like app blocking, usage monitoring, scheduled restrictions, and custom shield configurations.

📚 Full documentation → magrinj.github.io/expo-screen-time

Note: This module is iOS-only. Screen Time APIs are not available on Android.

Features

• Permission Management — Request and check Family Controls authorization
• App Blocking — Block apps, categories, and web domains using the native activity picker
• Web Domain Blocking — Programmatically block specific domains without user selection
• App Store Restrictions — Prevent app installation and removal
• Schedule Monitoring — Set up time-based blocking schedules
• Shield Customization — Customize the blocking screen appearance and button actions
• Usage Reports — Display device activity reports with customizable styling
• Token Labels — Display app/category/domain names and icons

Requirements

• iOS 16.0+
• Expo SDK 56+
• Apple Developer account with Family Controls capability

Installation

npm install expo-screen-time
# or
yarn add expo-screen-time
# or
bun add expo-screen-time

Quick start

Add the plugin to your app.json:

{
  "expo": {
    "ios": {
      "bundleIdentifier": "com.yourcompany.yourapp",
      "appleTeamId": "YOUR_TEAM_ID"
    },
    "plugins": ["expo-screen-time"]
  }
}

Then run a prebuild so the iOS extension targets are generated:

npx expo prebuild --clean

import ExpoScreenTime from 'expo-screen-time';

// Ask for Family Controls authorization, then block a selection from the picker.
await ExpoScreenTime.requestScreenTimePermissionsAsync();
ExpoScreenTime.blockSelection(selection);

Always re-run expo prebuild --clean when upgrading expo-screen-time or changing ios.bundleIdentifier. See Configuration.

Documentation

The full guide and API reference live at magrinj.github.io/expo-screen-time:

• Configuration & extension targets
• API reference — permissions, blocking, restrictions, monitoring, shields
• Components — activity picker, activity report, token labels
• Types
• Troubleshooting

The docs site is generated from website/ (Docusaurus). To work on it: cd website && bun install && bun start.

Example App

See the example/ directory for a complete app demonstrating all features:

cd example
bun install   # postinstall builds the plugin (../plugin/build) and symlinks the module
bun run ios

License

MIT

Credits

• expo-widgets — Expo's first-party config-plugin approach for generating Apple targets, which this library's target generation is modeled on
• @bacons/apple-targets — Evan Bacon's apple-targets plugin, the original inspiration
• Apple's Screen Time API documentation