Skip to Content
expo-screen-time

Types

As exported from expo-screen-time (source of truth: ExpoScreenTime.types.ts).

ScreenTimeFeature, PermissionStepId, PermissionStep

What the app intends to use, and the steps the user must allow for it — see Permissions.

type ScreenTimeFeature =
  | "blocking" | "monitoring" | "usageReports"
  | "shieldOpenApp" | "appRemovalProtection" | "webDomainBlocking";

type PermissionStepId =
  | "screenTime"      // iOS: the Family Controls prompt
  | "notifications"   // iOS: for shieldOpenApp
  // Android ids, so shared code can label every step; iOS never lists them:
  | "usageAccess" | "overlay" | "accessibility"
  | "batteryOptimization" | "backgroundAutostart" | "deviceAdmin";

type PermissionStep = {
  id: PermissionStepId;
  status: "granted" | "denied" | "undetermined" | "restricted" | "unknown";
  required: boolean;                     // needed by the requested features
  kind: "prompt" | "settings" | "guide"; // a system dialog on iOS
  error?: { code: string; message: string };
};

type ScreenTimePermissionOptions = {
  features?: ScreenTimeFeature[];        // default ["blocking", "monitoring"]
  member?: "individual" | "child";
};

type ScreenTimePermissionResponse = PermissionResponse & { steps: PermissionStep[] };

TokenHandle

Opaque, stable reference to a native token. Never parse or construct one in JS.

type TokenHandle = {
  handle: string; // opaque, stable across app launches
  type: "application" | "category" | "webDomain";
};

SelectionMetadata

Counts for a stored selection — no token data.

type SelectionMetadata = {
  applicationCount: number;
  categoryCount: number;
  webDomainCount: number;
};

OnSelectionChangeEvent

Payload of the picker's onSelectionChange (event.nativeEvent).

type OnSelectionChangeEvent = {
  metadata: SelectionMetadata;
  tokens: TokenHandle[];
};

TokenLabelProps

Props of TokenLabel; ApplicationLabel, CategoryLabel and WebDomainLabel take the same props without tokenType.

type TokenLabelProps = {
  style?: StyleProp<ViewStyle>;
  /** Optional — a handle is self-describing; given, the handle must be in it */
  selectionId?: string;
  handle: string; // opaque TokenHandle.handle
  tokenType: "application" | "category" | "webDomain";
  displayMode?: "icon-only" | "title-only" | "title-and-icon"; // default title-and-icon
};

DeviceActivitySchedule

type DeviceActivitySchedule = {
  intervalStart: DateComponents;
  intervalEnd: DateComponents;
  repeats: boolean;
  warningTime?: number; // seconds
};

type DateComponents = {
  hour: number;     // 0-23
  minute: number;   // 0-59
  second?: number;  // 0-59
  weekday?: number; // 1 = Sunday … 7 = Saturday
};

BlockMode

type BlockMode =
  /** Shield the selection (default). */
  | "blocklist"
  /**
   * Shield every app EXCEPT the selection's apps, and the whole web. The
   * selection may hold applications only (else INVALID_CONFIG).
   */
  | "allowlist";

Accepted by blockSelection and MonitoringConfiguration.mode. The blocking page lists what an allowlist never shields, how it combines with other sources, and why temporaryUnlock rejects while one is active.

MonitoringConfiguration

type MonitoringConfiguration = {
  /** Stable identity: events, shield configs and getMonitoredActivities use it */
  activityName: string;
  /** intervalEnd at or before intervalStart crosses midnight */
  schedule: DeviceActivitySchedule;
  /** Selection to block while the interval is active — a stored selection ID */
  selectionId?: string;
  /** How selectionId is applied while the interval is active (default "blocklist") */
  mode?: BlockMode;
  events?: DeviceActivityEventThreshold[];
  /** Restrict to specific weekdays (1 = Sunday … 7 = Saturday) */
  weekdays?: number[];
};

type DeviceActivityEventThreshold = {
  eventName: string;
  /** Stored selection to meter (and to shield with blockOnThreshold) */
  selectionId: string;
  threshold: number; // seconds of usage within the interval
  includesPastActivity?: boolean;
  /** Shield selectionId from the threshold until the interval ends */
  blockOnThreshold?: boolean;
};

One activity is registered per activityName, weekdays included: it costs one of the 19 activities you can monitor at once, and its events carry that name. Occurrences on unselected weekdays are ignored (no block, no events); an occurrence that crosses midnight belongs to the weekday on which it starts. A one-off schedule (repeats: false) with weekdays covers its next occurrence on a selected weekday (see monitoring).

ShieldConfig

Text elements and buttons are nested objects.

type ShieldConfig = {
  title?: { text: string; color?: string };
  subtitle?: { text: string; color?: string };
  icon?: string;                    // SF Symbol name
  backgroundColor?: string;         // hex color
  backgroundBlurStyle?: UIBlurEffectStyle; // 'light' | 'dark' | 'regular' | …
  primaryButton?: { text: string; color?: string; backgroundColor?: string };
  secondaryButton?: { text: string; color?: string };
};

ShieldAction

What a shield button does — see Shield Actions.

type ShieldAction =
  | "close"                                // dismiss; the block stays
  | "unblock"                              // lift the pressed target until the next block
  | "defer"                                // keep the shield up; the press is recorded
  | { type: "snooze"; duration: number }   // lift the pressed target for `duration` seconds of use
  | { type: "openApp" };                   // bring the host app forward (iOS: a notification to tap)

type ShieldActionType = "close" | "unblock" | "defer"; // the string actions alone

Snooze is expressed as an object with its duration in seconds of use of the pressed target (at least 30) — see Snooze. openApp posts a notification on iOS — see Open app.

ShieldActionConfig

type ShieldActionConfig = {
  primaryAction: ShieldAction;
  secondaryAction?: ShieldAction;
};

MonitorEvent

type MonitorEvent = {
  activityName: string;
  eventType: MonitorEventType;
  eventName?: string; // for threshold events
  timestamp: number;  // Unix milliseconds
};

type MonitorEventType =
  | "intervalDidStart"
  | "intervalDidEnd"
  | "eventDidReachThreshold"
  | "intervalWillEndWarning"
  | "eventWillReachThresholdWarning";

TemporaryUnlockGrant

Result of temporaryUnlock. There is deliberately no expiresAt — the budget is spent by usage, not by the clock.

type TemporaryUnlockGrant = {
  budgetSeconds: number;      // granted budget (after the 30s floor)
  grantedAt: number;          // Unix milliseconds
  meteringSeconds: number;    // the budget is spent in steps of this many seconds
  target: TokenHandle | null; // the one target lifted, or null for a whole-block unlock
};

meteringSeconds is 30 for budgets up to 30 minutes, then ceil(budget / 60) (120 for a 2-hour budget): getRemainingUnlockSeconds() moves by that much at a time. target echoes the { target } option of a targeted unlock.

ShieldInteraction

One press of a shield button. Returned by drainShieldInteractions. Presses on the same target within 2 seconds collapse into one.

type ShieldInteraction = {
  button: "primary" | "secondary";
  timestamp: number;            // Unix milliseconds
  target: TokenHandle | null;   // what was shielded — render it with <TokenLabel>
  activityName: string | null;  // monitored activity behind the block; null for the manual block
};

target is the pressed app, web domain or category (an app shielded through its category reports the category), as the handle getTokens returns for it. activityName is resolved like the shield config: a threshold block, else the most recently started schedule covering the target, else null (the manual block, or no active block owns the shield any more). Both are null for interactions recorded before these fields existed.

EnforcementGap

A period during which blocks were intended but not enforced — see getEnforcementGaps.

type EnforcementGap = {
  from: number;            // Unix ms
  to: number | null;       // null while the gap is still open
  reason:
    | "stoppedByUser"        // Android: Task Manager "Stop", force stop
    | "permissionRevoked"    // Android: a step turned off in Settings
    | "killedBySystem"       // Android: the system killed the engine
    | "authorizationRevoked" // iOS: Screen Time access revoked
    | "unknown";
  // Android, builds that opt into the accessibility engine: only the apps
  // opened from a work profile, Private Space or a clone went unenforced.
  // Absent: every blocked app.
  scope?: "otherProfiles";
};

ScreenTimeErrorCode

Every rejected promise and thrown error from the module carries one of these codes. Narrow a caught value with isScreenTimeError, then branch on code:

import ExpoScreenTime, { isScreenTimeError } from "expo-screen-time";

try {
  await ExpoScreenTime.temporaryUnlock(15 * 60);
} catch (error) {
  if (isScreenTimeError(error) && error.code === "NO_ACTIVE_BLOCK") {
    return; // nothing to unlock
  }
  throw error;
}
CodeWhen
UNAUTHORIZEDFamily Controls authorization is missing (startMonitoring).
UNSUPPORTEDThe OS version is too old for the call, or temporaryUnlock while an allowlist block is active.
SELECTION_NOT_FOUNDblockSelection with a selectionId that was never saved; startMonitoring with mode: "allowlist" over one.
NO_ACTIVE_BLOCKtemporaryUnlock while nothing is blocked.
EXCESSIVE_ACTIVITIESstartMonitoring for a 20th activity (limits.maxMonitoredActivities is 19), or when the temporary-unlock meter or a shield snooze holds the remaining DeviceActivity slot.
INTERVAL_TOO_SHORTA schedule shorter than 15 minutes.
INTERVAL_TOO_LONGA schedule longer than a week.
INVALID_DATE_COMPONENTSA schedule the system rejects as invalid dates.
INVALID_CONFIGA missing or malformed argument: no activityName or schedule, a reserved activity name, missing interval bounds, an unknown mode, or an allowlist whose selection holds categories or web domains, or no app at all.
MONITORING_ERRORThe system refused the monitoring request for another reason; the message carries its description.
MONITORING_ROLLBACK_FAILEDRe-registering an activity failed and its previous schedule could not be restored: the activity is no longer monitored.

Errors raised by Expo itself (for example ERR_ARGUMENT_CAST on a wrong argument type) are not ScreenTimeErrors. SCREEN_TIME_ERROR_CODES lists every code at runtime.

If error.code is always undefined, see Troubleshooting.

On this page