Skip to Content
expo-screen-time
API Reference

Permissions

One call site: the library reports the steps the user must allow as data, and your onboarding explains each one. Which steps are listed depends on the features you intend to use.

getScreenTimePermissionsAsync(options?)

The current status of every step the requested features need, without prompting.

const response = await ExpoScreenTime.getScreenTimePermissionsAsync({
  features: ["blocking", "shieldOpenApp"],
});
// response.granted: boolean
// response.status: 'granted' | 'denied' | 'undetermined'
// response.canAskAgain: boolean
// response.steps: [
//   { id: 'screenTime', status, required: true, kind: 'prompt', error? },
//   { id: 'notifications', status, required: true, kind: 'prompt', error? },
// ]

Options

OptionTypeDefault
featuresScreenTimeFeature[]['blocking', 'monitoring']What the app will use; decides which steps are listed and required. On iOS every feature rests on the screenTime step; shieldOpenApp adds the notifications step. On Android, blocking and monitoring need overlay and usageAccess; usageReports needs usageAccess; appRemovalProtection needs deviceAdmin. A feature the build does not contain (android.features) rejects UNSUPPORTED, naming it; the default narrows to the default features the build has.
member'individual' | 'child''individual'child requests Family Sharing authorization for a child account, approved by a parent. On an account that is not a child in a family, the request fails with the step error invalidAccountType. iOS reads it only when requesting screenTime; Android makes the notifications and deviceAdmin steps required for a child (Google Play's parental-control rules demand a persistent notice), so it is read when listing the steps too.

Steps on iOS

StepiOSStatus read from
screenTimeAlways listed, required. The Family Controls system prompt.AuthorizationCenter
notificationsListed, and required, when features includes shieldOpenApp: a shield's openApp action reaches the app through a local notification the user taps. The prompt asks for alerts and sounds.UNUserNotificationCenter (authorized, provisional and ephemeral are granted)

Steps on Android

Android has no single Screen Time authorization: the enforcement engine rests on special-access toggles the user flips in Settings, one screen each. The library lists them in onboarding order; kind says how each one is granted.

A step is listed only when the build has what it grants: no overlay without the shield, no deviceAdmin without its receiver, no engine steps without the engine (the android.features option removes them).

StepListed forRequiredKindWhat it is
overlayblocking, monitoring (in a build with the shield)yessettingsSettings › Display over other apps. The shield is an Activity the engine launches from the background, which Android allows once this is held. Requested first: it also lets the library bring the user back to the app from the next screens.
usageAccessblocking, monitoring, usageReportsyessettingsSettings › Usage access. How the engine sees which app is in the foreground.
accessibilityblocking, in a build whose config plugin declared the accessibility service (android.accessibilityEngine)nosettingsSettings › Accessibility: the service's own page where Android shows it (Android 10+), else the list. Turns on the second detector, which hears a blocked app opened from a work profile, Private Space or a cloned app; the main profile is enforced without it, which is why it is recommended, not required. Show your disclosure first (below). restricted when Android 17's Advanced Protection is on (it disables every accessibility service that is not an accessibility tool) or under restricted settings.
notificationsblocking, monitoring (Android 13+)for member: 'child'promptThe runtime notification permission for the engine's persistent notice. Without it the service still runs; the notice moves to the Task Manager.
deviceAdminblocking, monitoring (in a build with the device admin), appRemovalProtectionfor appRemovalProtection and member: 'child'settingsDevice admin activation (no policy). While active, Settings disables "Force stop", "Uninstall" asks to deactivate the admin first, and the system's Task Manager hides the engine's "Stop" button. Deactivating takes the toggle in Settings › Security › Device admin apps plus a confirmation whose text is the expo_st_device_admin_disable_warning string resource (override it in your app's res/values to localise it); it does not stop the engine.
batteryOptimizationblocking, monitoringnosettingsThe system's battery-optimization list. The library opens the list and never requests REQUEST_IGNORE_BATTERY_OPTIMIZATIONS (not an acceptable use for a blocker on Google Play). With the exemption, an engine the system killed restarts directly from the background; without it, the library restarts it through the overlay permission, which is why overlay is required (see blocking). This step or deviceAdmin keeps the restart within minutes on battery: either one exempts the app from the standby buckets' alarm limit.
backgroundAutostartblocking, monitoring, on Xiaomi, Oppo, Realme, Vivo, Huawei, Honor and OnePlusnoguideThe vendor's autostart screen. Nothing reads it back: its status stays unknown.

A settings toggle that is off reads undetermined until the app has sent the user to that screen once, and denied after, so an onboarding UI can tell "never asked" from "went there and came back without it". restricted is reported when Android 13+ keeps the toggles locked for a sideloaded app ("restricted settings", lifted from App info), for overlay on a low-RAM device, where the system never grants it, and for accessibility under Android 17's Advanced Protection. screenTime is never listed on Android, and accessibility only in a build that opts into the accessibility engine.

A step's status adds two values to Expo's:

  • restricted: the OS refuses to let this user grant access (Screen Time restrictions, a managed device, Android's restricted settings). The response then reports status: 'denied' and canAskAgain: false; the user has to change the restriction in Settings.
  • unknown: the status cannot be read back.

The response

Expo's PermissionResponse plus the ordered steps behind it:

  • granted is true when every required step is granted;
  • status is 'granted' if so; else 'denied' if a required step is denied or restricted; else 'undetermined';
  • canAskAgain is true when no required step is restricted and every required step still to grant can show its prompt. Family Controls shows its prompt again after a denial; the notification prompt is shown once, so a denied notifications step reads canAskAgain: false until the user allows it in Settings.

requestScreenTimePermissionsAsync(options?)

Advances onboarding by one step and resolves with the whole response: options.step if given, else the first required step not yet granted. Call it again for the next step, so your UI can explain each one. A step already granted is not asked again; when nothing is pending, nothing is prompted.

On Android a settings or guide step opens its screen and the promise resolves when the user comes back to the app, with fresh statuses. For usageAccess and overlay the library also watches the toggle and brings the app back the moment it flips, which Android honours once overlay is held. For accessibility it watches the enabled-services setting the same way. A screen that could not be opened (an ActivityNotFoundException on an unusual device) is not an error: the step keeps it in error and the response says so. A step the platform does not have (screenTime), or accessibility in a build that does not declare the service, rejects with INVALID_CONFIG.

The accessibility step and its disclosure

Google Play requires a prominent disclosure inside the app, before the user is sent to Settings › Accessibility, during normal use (the store listing or a website is not enough): what the service does, and the user's consent. The library cannot show it for you (it is UI), and the step is never part of the "first required step" default, so the only way to reach it is an explicit step: "accessibility" call, which is where your disclosure belongs:

import { Alert } from "react-native";
import { requestScreenTimePermissionsAsync } from "expo-screen-time";

function askForAccessibility() {
  Alert.alert(
    "Block apps everywhere on this phone",
    "To block the apps you chose in your work profile, Private Space and " +
      "cloned apps too, this app uses Android's Accessibility service. " +
      "Android tells it when one of those apps opens, so it can show the " +
      "blocking screen. It does not read what is on your screen, collects " +
      "no personal data and sends nothing off your phone. You can turn it " +
      "off at any time in Settings › Accessibility.",
    [
      { text: "Not now", style: "cancel" },
      {
        text: "Continue to Settings",
        onPress: () => requestScreenTimePermissionsAsync({ step: "accessibility" }),
      },
    ],
  );
}

A French listing ships the same text in French:

Bloquer les applis partout sur ce téléphone — Pour bloquer aussi les applis choisies dans votre profil professionnel, votre Espace privé et vos applis clonées, cette appli utilise le service d'accessibilité d'Android. Android la prévient quand l'une de ces applis s'ouvre, afin d'afficher l'écran de blocage. Elle ne lit pas ce qui est à l'écran, ne collecte aucune donnée personnelle et n'envoie rien hors du téléphone. Vous pouvez la désactiver à tout moment dans Réglages › Accessibilité. [Continuer vers les Réglages] [Pas maintenant]

The disclosure's data sentence is this example's: keep it only if it is true of your whole app. The Settings page shows the expo_st_accessibility_description string next to the toggle; the library's default says only what the service does (the window-state events, no screen content, the off switch), so add your app's data practices in your override, and only true ones: Play reads it against your declaration, so keep the two in step. Ask the users who need the coverage (an app can check for other profiles itself) rather than everyone: a chained settings screen loses users. The response's granted never depends on this step. Once enabled, the lost coverage while the service is down is reported by getEnforcementGaps with scope: "otherProfiles".

On iOS 16 and later it never rejects for a refused prompt: a failed request resolves with the resulting status, and the reason in the step's error. A step whose prompt the OS will not show again (a denied notifications step) is not requested: the response comes back unchanged, with canAskAgain: false, and your UI should send the user to Settings. Earlier iOS versions reject with UNSUPPORTED; a step this platform does not have (an Android id), or one the requested features do not list, rejects with INVALID_CONFIG.

// The first pending step (screenTime, then notifications)
let response = await ExpoScreenTime.requestScreenTimePermissionsAsync({
  features: ["blocking", "shieldOpenApp"],
});

// A specific step, from a checklist
response = await ExpoScreenTime.requestScreenTimePermissionsAsync({
  features: ["blocking", "shieldOpenApp"],
  step: "notifications",
});

Options

features and member as above, plus:

OptionType
stepPermissionStepIdThe step to request. Default: the first required step not granted.
await ExpoScreenTime.requestScreenTimePermissionsAsync({ member: "child" });

The Screen Time authorization is device-wide: once granted, by either member, later requests resolve at once without a prompt.

Errors

error is present on a step when its last request failed: for screenTime, code is the FamilyControlsError case name (restricted, invalidAccountType, authorizationCanceled, networkError, unavailable, …) and message its description; for notifications, an error thrown by the request (a refusal is not an error: the step reads denied). It disappears once the step is granted, and is kept for the app's lifetime only.

const response = await ExpoScreenTime.requestScreenTimePermissionsAsync();
const step = response.steps.find((s) => s.id === "screenTime");
if (step?.status === "restricted") {
  // explain how to lift the restriction in Settings › Screen Time
} else if (step?.error?.code === "networkError") {
  // offer to retry
}

An onboarding checklist

import {
  requestScreenTimePermissionsAsync,
  useScreenTimePermissions,
  type ScreenTimePermissionOptions,
} from "expo-screen-time";
import type { ReactNode } from "react";
import { Button } from "react-native";

const options: ScreenTimePermissionOptions = {
  features: ["blocking", "shieldOpenApp"],
};

const titles: Record<string, string> = {
  screenTime: "Allow Screen Time",
  notifications: "Allow notifications",
  overlay: "Allow display over other apps",
  usageAccess: "Allow usage access",
  accessibility: "Block apps in every profile",
  deviceAdmin: "Activate device admin",
  batteryOptimization: "Exempt from battery optimization",
  backgroundAutostart: "Allow autostart",
};

function PermissionGate({ children }: { children: ReactNode }) {
  const [permission, , refresh] = useScreenTimePermissions(options);
  if (!permission) return null;
  if (permission.granted) return children;

  const pending = permission.steps.filter(
    (step) => step.required && step.status !== "granted",
  );
  return (
    <>
      {pending.map((step) => (
        <Button
          key={step.id}
          title={titles[step.id] ?? step.id}
          onPress={async () => {
            await requestScreenTimePermissionsAsync({ ...options, step: step.id });
            await refresh();
          }}
        />
      ))}
    </>
  );
}

The same gate lists one step on iOS and several on Android, each requested with one tap; recommended steps (required: false) make a good second screen, after the app works.

useScreenTimePermissions(options?) Hook

Expo-style permissions hook for React components. options takes features and member, plus the hook's own get and request flags; the request method advances the first pending step.

function MyComponent() {
  const [permission, requestPermission] = useScreenTimePermissions();

  if (!permission?.granted) {
    return <Button title="Grant Access" onPress={requestPermission} />;
  }

  return <Text>Permission granted!</Text>;
}

On this page