Blocking
The functions below work on iOS and Android. On iOS the OS enforces the block
(getCapabilities().blocking is "enforced"); on Android the library's own
engine does, and the user can stop it ("friction"): the Android
notes at the end of this page say what differs.
Apps & Categories
blockSelection(selectionId: string, options?: { mode?: BlockMode })
Shield every app, category, and web domain in a stored selection. The selection
is created by the <ActivityPicker /> under
the same ID.
The manual block is one block source. Schedules started with
startMonitoring and their blockOnThreshold events are
separate sources, and the effective block is the union of every active source:
calling blockSelection again replaces only the manual selection, and a
schedule ending never lifts the manual block. An explicit block supersedes
any temporary unlock and every shield snooze in
progress.
// 1. The user picked apps in <ActivityPicker selectionId="my-blocklist" />
// 2. Apply the shield:
ExpoScreenTime.blockSelection('my-blocklist');Throws SELECTION_NOT_FOUND if no selection exists under that ID, and
INVALID_CONFIG for an allowlist whose selection holds categories or web
domains (below).
Allowlist mode
{ mode: 'allowlist' } turns the rule around: every app is shielded except
the selection's apps. Use it for a focus mode ("only Calendar, Mail and
Slack") or a child profile.
// The user picked the apps to KEEP in <ActivityPicker selectionId="focus-apps" />
ExpoScreenTime.blockSelection('focus-apps', { mode: 'allowlist' });- Applications only, at least one. An allowlist selection may not hold
categories or web domains: the call throws
INVALID_CONFIG(iOS applies an allowlist withActivityCategoryPolicy.all(except:), which takes application tokens only; Android enforces the same rule). An empty selection throwsINVALID_CONFIGtoo, a missing oneSELECTION_NOT_FOUND. CheckgetSelectionMetadatabefore offering the option, or pick with a picker that only lists apps. The selection is read live: a selection edited after it was applied changes the running allowlist at the next re-projection — one edited to hold categories or domains keeps allowing its apps only, and one emptied allows nothing (every app is shielded). - Never shielded (measured on iOS 26): your own app, Phone and Settings,
so the user can always come back and change the rule.
unblockAll()from your app is the recovery path. A shield action of'unblock'lifts the pressed app too, provided iOS reports the shield by the app (see the snooze bullet). - The web is shielded whole. The application policy does not reach Safari, so an allowlist also sets a web-domain policy of "every domain": Safari opens, but every page shows the shield. Other browsers are ordinary apps and are shielded unless allowed. Consequently Safari cannot be allowed by an allowlist today; allow a third-party browser instead if the user needs the web.
- Union with other sources. The effective block is still the union of
every active source — a target is shielded if any source shields it.
An app allowed by the allowlist but listed by an active schedule or
blockOnThresholdblocklist is shielded, by that source. One exception, inside a single schedule: a category in ablockOnThresholdselection cannot override that schedule's own allowlist — list the apps directly (see monitoring). Two allowlists at once (a manual one and a schedule) allow only the apps in both. - Snoozes are per app: a snoozed app is excepted from the allowlist
until its budget is spent — when iOS reports the shield by the app. When
it reports an allowlist shield by the app's category instead,
'unblock'and snooze buttons close the shield without lifting anything (there is no way to single out the app); the press is still recorded. Which callback iOS uses for an allowlist shield is not yet measured on a device. temporaryUnlockwithout a target rejectsUNSUPPORTEDwhile an allowlist is active: the unlock is a usage budget over the shielded apps, and "every other app" cannot be metered. Lift the block withunblockAll()and apply it again, or put the allowlist on a schedule.- The mode is persisted with the selection: a relaunch, a relock or the
monitor extension re-applying the block restore the same allowlist.
isBlocked()istruewhile an allowlist is in force.
unblockAll()
Lift every active block now — the manual block, every schedule and threshold block in progress — and clear the web-domain filters; a temporary unlock and every shield snooze in progress end. Monitoring keeps running: a schedule re-applies its block at its next interval start.
ExpoScreenTime.unblockAll();isBlocked(): boolean
Whether any source currently shields something — reflects the real
ManagedSettings state, not what you last asked for. false during a temporary
unlock. true while a snooze lifts one app and others stay shielded.
const blocked = ExpoScreenTime.isBlocked();Web Domains
Block specific domains without user selection (independent from
blockSelection's domain shields).
blockWebDomains(domains: string[])
ExpoScreenTime.blockWebDomains(['facebook.com', 'instagram.com', 'tiktok.com']);unblockWebDomains(domains: string[])
ExpoScreenTime.unblockWebDomains(['facebook.com']);unblockAllWebDomains()
ExpoScreenTime.unblockAllWebDomains();getBlockedWebDomains(): string[]
Domains currently blocked via blockWebDomains(). The list is persisted, so
it survives app relaunches.
const domains = ExpoScreenTime.getBlockedWebDomains();
// ['facebook.com', 'tiktok.com']Temporary Unlock (earned time)
Let the user "earn" time inside blocked apps without giving up the block. The budget is usage-based, not wall-clock: it is only spent while a blocked app is actually in the foreground — it pauses when the user leaves and resumes when they come back. The shield re-applies automatically once the budget is spent (enforced by the DeviceActivityMonitor extension, so it works even if your app is killed), and unspent budget expires at midnight.
temporaryUnlock(budgetSeconds, options?): Promise<TemporaryUnlockGrant>
Without options.target, suspends every active block — the manual block, the
schedules and threshold blocks in progress — for a usage budget metered over
all of them. Rejects with NO_ACTIVE_BLOCK if nothing is blocked, and with
UNSUPPORTED while an allowlist is active (its shield covers
every other app, which no usage meter can count). Budgets below 30 seconds are
raised to 30 (iOS usage thresholds are unreliable under that). Calling it
again replaces the active unlock with a fresh budget covering everything
blocked or suspended at that moment — a renewal never rejects
NO_ACTIVE_BLOCK while something is restorable; calling blockSelection
cancels it.
The grant's meteringSeconds is the step the budget is spent in: 30 seconds
for budgets up to 30 minutes, then ceil(budget / 60) (120 seconds for a
2-hour budget). The remaining time only ever moves by that much, so say
"about N minutes" rather than counting down.
What the grant suspended stays suspended until relock() or expiry, whatever
happens in between: a threshold firing or the system reporting an interval
start does not re-shield it. A source that starts during the grant — a
schedule reaching its start time, a blockOnThreshold event for a selection
that was not suspended, or one firing again in a new interval after its
activity was stopped and started again — is outside the grant: it is shielded
and not metered.
await ExpoScreenTime.blockSelection('social-apps');
// ... user earns 15 minutes ...
const grant = await ExpoScreenTime.temporaryUnlock(15 * 60);
// { budgetSeconds: 900, grantedAt: 1720512000000, meteringSeconds: 30, target: null }Unlocking one target
temporaryUnlock(budgetSeconds, { target }) lifts one app, category or
web domain — target is a TokenHandle from
getTokens or from a shield interaction — for
budgetSeconds of its use, and nothing else: every other shielded app
stays shielded and the sources covering the target stay active. It is the
shield snooze action granted from your app instead of
from the shield, with the same mechanism, floor and accounting; the grant's
target echoes the handle back.
// The app the user just hit a shield on, from drainShieldInteractions()
const grant = await ExpoScreenTime.temporaryUnlock(3 * 60, { target: press.target });
// { budgetSeconds: 180, grantedAt: …, meteringSeconds: 30, target: { handle, type: 'application' } }- The target must be shielded by an active block (suspended by a whole-block
unlock in progress or not), else
NO_ACTIVE_BLOCK. Tokens are opaque, so an app shielded only through its category is not known to be shielded: target the category — the handle the shield reports for such an app. - An app or a web domain an allowlist shields can be
targeted (it is excepted from the allowlist, like a snoozed app), unlike
the whole-block unlock. A category cannot while an allowlist is active
(
UNSUPPORTED): the allowlist shields every app, and "every app" cannot except a category, so nothing would open. - A handle that does not decode to a token rejects
INVALID_CONFIG. Pass handles unchanged: a handle from another device, or of another type than itstypesays, is misuse the module cannot detect. When no DeviceActivity slot is free for the meter,EXCESSIVE_ACTIVITIES. - Targeted grants are independent of the whole-block unlock:
isTemporarilyUnlocked()andgetRemainingUnlockSeconds()describe the whole-block one only, and either can end without ending the other. A second targeted grant — or a snooze press — on the same target replaces the first; grants on other targets run concurrently, each holding one DeviceActivity slot until it is spent or the day ends. relock(),blockSelection()andunblockAll()end every targeted grant (and every snooze);stopMonitoringand a schedule ending do not.
getRemainingUnlockSeconds(): number
Seconds left on the active whole-block budget, or 0. Consumption is reported
by the monitor extension in meteringSeconds steps (30 seconds for budgets
up to 30 minutes), only while a blocked app is in use — don't render this
as a smooth countdown. Reading 0 after a grant also re-applies the shield as
a backstop. Targeted grants are not reported here.
isTemporarilyUnlocked(): boolean
Whether a whole-block earned-time budget is currently active. false while
only targeted grants or snoozes are in progress.
relock(): void
Ends any active unlock — the whole-block one, every targeted grant and every shield snooze — immediately and restores exactly the sources that are still active: the manual block, and every schedule (plus its threshold blocks) whose interval is still in progress. Safe to call when nothing is unlocked.
Shield interactions
drainShieldInteractions(): ShieldInteraction[]
Read-and-clear the queue of shield button presses, recorded natively by the ShieldAction extension. Call it when your app foregrounds and persist the results app-side to power "you were blocked N times" stats.
Each ShieldInteraction says which button
was pressed, when, what was shielded (target, a
TokenHandle for the app, web domain or category)
and which block shielded it (activityName, the monitored activity whose
schedule or threshold owns the shield, null for the manual block).
Presses on the same target within 2 seconds collapse into one interaction (tapping both buttons of one shield is one blocked attempt); presses on different targets in that window are separate interactions, so two apps opened back to back count twice — unless both are shielded through the same category, which iOS reports as one target.
const attempts = ExpoScreenTime.drainShieldInteractions();
// [{ button: 'primary', timestamp: 1720512000000,
// target: { handle: '…', type: 'application' }, activityName: 'work-hours' }, ...]
blockedCount += attempts.length;target is the same handle getTokens returns for that
token, so it renders with a label and a
selection that contains it — the blocked selection, or the activity's:
{attempts.map((attempt) =>
attempt.target ? (
<TokenLabel
key={attempt.timestamp}
selectionId="my-blocklist"
handle={attempt.target.handle}
tokenType={attempt.target.type}
displayMode="title-and-icon"
/>
) : null,
)}An app shielded through a category reports the category (iOS identifies
such a shield by its category only). target is null when no handle could
be derived; activityName is null for the manual block and when no active
block owns the shield any more. Both are null for interactions recorded by
versions before these fields existed (they still drain).
Android
getCapabilities().blocking is "friction" on Android: the block holds,
but the user can lift it through routes the app cannot close, and
getEnforcementGaps() reports
when that happened.
blockSelection,unblockAll,isBlockedkeep the iOS contract: the same validation order and codes (SELECTION_NOT_FOUNDbefore the mode is looked at,INVALID_CONFIGfor a bad mode and for an allowlist that holds categories or web domains or no app at all), one manual block that a second call replaces,isBlocked()true while that block shields something (a blocklist over an empty selection shields nothing; an allowlist always shields). The selection's apps are captured when the block is applied, as iOS projects them into its store: editing the selection afterwards changes nothing until the nextblockSelection. Web domains are not blocked on Android (webDomainBlockingisfalse).- The app restrictions are block sources too.
denyAppRemoval()anddenyAppInstallation()add, below your blocks, a source over the system's uninstall dialog, the stores and the package installer. They are not blocks:unblockAll(),isBlocked(), the temporary unlock and the snoozes leave them alone, and a restriction alone keeps the engine polling exactly as a block does. - How it is enforced (
"friction", not"enforced"): a foreground service in its own process reads the apps on screen from UsageStats every 100 ms while the screen is on and a block is in force, and starts a blocking Activity, the shield, over the blocked app. Measured on a Pixel 8a: the shield is up about 120 ms after the app comes forward (p95 176 ms), and the user sees the app's splash, never its content. Nothing is polled with the screen off or without a block. The user can still stop the engine (Task Manager, force stop, revoking usage access or the overlay permission); such periods are reported bygetEnforcementGaps, which is why the capability is"friction". - The second detector: other profiles. Usage access reports the main
profile only: a blocked app opened from a work profile, Private
Space or a cloned app (Samsung Dual Messenger) is invisible to the
poll and is never shielded. A build that opts into the
accessibility engine
declares an accessibility service next to the engine; once the user
enables it (the recommended
accessibilitystep, after your disclosure), Android tells the engine the instant a window of a restricted app comes forward, from every profile, and the same shield is drawn over it. The service is scoped to the restricted apps, asks for window-state events only and cannot read screen content. It runs next to the poll, never instead of it: for a main-profile app the two agree and the earlier signal wins (measured on a Pixel 8a, both are as fast: p95 180 ms against 176 ms); when the service is off, crashed or blocked, the main profile is enforced as before and the lost coverage is reported as a gap withscope: "otherProfiles". Limits in this version:- The selection still lists main-profile apps: the coverage is the same package in another profile. An app installed only in a profile cannot be picked, and an allowlist never shields one either, since what an allowlist blocks is computed from the main profile's apps.
- Use from a profile is not metered: a temporary unlock, a snooze or a usage threshold counts main-profile seconds only, while the lift applies to the package in every profile.
- A restricted app that hands the screen to another app at once (a splash screen opening an allowed app) can leave its shield over that app: the window event says only that the restricted app came forward, and from another profile nothing can confirm that it left. Closing the shield returns to the app underneath.
- If the system kills the engine, it comes back. Android restarts a
killed foreground service by itself within seconds; when it refuses (an
app in the background may not start a foreground service without an
exemption), the library retries under the overlay permission and, failing
everything else, a watchdog alarm brings the engine back within
3.5 minutes of its last heartbeat while the screen is on and
unlocked, or within seconds of the next unlock (nothing can be opened
with the screen off, and no battery is spent on wakeups overnight).
On battery, that bound needs the
deviceAdminor thebatteryOptimizationstep. Without either, Android may put an app the user rarely opens in itsrarestandby bucket, which allows the app one alarm per hour. A Pixel did so within an hour of the last use. A stop made while the phone stays in use is still repaired within minutes, but a second stop within the hour, or a stop followed by locking the phone and leaving it asleep, can leave the engine down for up to an hour. ThebatteryOptimizationstep also makes the restart direct. A "Force stop" stays final until the app is opened again (Android cancels the app's alarms); a Task Manager "Stop" does not cancel them, so the engine returns within the same bound and the stop is reported as astoppedByUsergap of a few minutes. A device the user put in restricted battery mode cannot run a foreground service at all; that period is reported as a gap. - Allowlist = launchable apps.
{ mode: 'allowlist' }shields every app with a launcher entry except the selection's apps. Apps without a launcher entry (permission dialogs, the share sheet, the document picker) are reached from an allowed app and are never shielded. - Never shielded, in either mode: your own app, every home launcher, the system UI, the default dialer and the emergency app, the current keyboard, and Settings. Settings stays open for the same reason it does on iOS: the user must always be able to re-grant a permission or change the device, and a focus tool must not hold the phone hostage. Revoking the engine's permissions from there is the documented friction, not a hole the shield papers over.
- Picture-in-picture does not bypass the block on Android 10+: when the blocked app's pinned window is found floating over the shield, whether it was opened before or after the block, the engine evicts it (one pinned window exists per screen, and the library briefly takes it). A window opened in the last 3 seconds before the block starts is evicted once it has been paused that long, so an ordinary app switch is never mistaken for one. Android 7–9 report no "stopped" event, so a PiP window cannot be told from an app that left, and is not evicted there. Screen pinning (a Settings toggle) keeps every other task from starting, the shield included; the engine records it as a gap. In split-screen, the shield covers the whole screen: Android gives a background-started task no way into one pane. The split pair survives underneath, so the other app is not closed; it comes back with the pair from Recents (and the blocked app with it, shielded again). On a layout the shield cannot take over (a tablet or desktop pane beside it), the engine sends the user Home instead.
- Permissions: blocking needs the
usageAccessandoverlaysteps. Without the overlay permission the engine cannot start the shield from the background: it logs the gap and stops polling rather than burn battery. - Temporary unlock keeps the contract above, with the engine as the
meter:
temporaryUnlock(budget)suspends every source in force (the manual block, the schedules and threshold blocks in progress, by occurrence) and the budget is spent only while one of the apps those sources shielded is in the foreground with the screen on, in exact seconds —meteringSecondsis1, sogetRemainingUnlockSeconds()moves one second at a time. The same codes apply (NO_ACTIVE_BLOCK,UNSUPPORTEDunder an allowlist,INVALID_CONFIG), a renewal replaces the grant,isBlocked()readsfalsewhile everything is suspended, and the grant survives the engine process (it is persisted with its meter at most once a second while in use). When the budget is spent, or at midnight, the shields come back by themselves: the engine recomposes the sources and the app still on screen is shielded within about a second, whether or not your app runs.temporaryUnlock(budget, { target })lifts one app the same way a shield snooze does; a category or web-domain handle is never shielded here (NO_ACTIVE_BLOCK, orUNSUPPORTEDfor a category under an allowlist, as on iOS), and a handle that does not resolve on this install isINVALID_CONFIG.relock()ends the unlock, every snooze and every shieldunblock. - Shield interactions are recorded by the shield itself, one per button
press (collapsed per app within 2 s, 200 kept), with the app's handle and
the owning activity;
drainShieldInteractions()reads and clears them.