Shields
The configuration below is drawn by iOS; on Android the library draws the
shield itself from the same ShieldConfig (Android notes).
Shield Configuration
Requires the `ShieldConfigurationExtension` target
setShieldConfig(config: ShieldConfig)
Set the default shield (blocking screen) appearance. Text elements and buttons
are nested objects — see ShieldConfig.
ExpoScreenTime.setShieldConfig({
backgroundColor: '#1a1a2e',
backgroundBlurStyle: 'dark',
icon: 'hand.raised.fill', // SF Symbol name
title: { text: 'App Blocked', color: '#ffffff' },
subtitle: { text: 'This app is restricted during work hours', color: '#aaaaaa' },
primaryButton: { text: 'OK', color: '#ffffff', backgroundColor: '#4a4ae8' },
secondaryButton: { text: 'Not now', color: '#ffffff' },
});Default text colours
Every color is optional. What you get when you leave one out depends on
whether the element sits on a background you chose:
- No
backgroundColor: the system defaults, which follow the device's light or dark appearance (on iOS the label colours and the system blue; on Android the library's equivalent palette). - A
backgroundColor: defaults chosen for contrast against it, the same on both platforms. The title is white or black, whichever contrasts more (at least 4.58:1 against any opaque colour, so always over the WCAG AA 4.5:1 bar for normal text). The subtitle is the title colour mixed into the background at 70 %, so it reads as secondary, made more opaque in 5 % steps where that falls under 3:1 (the AA bar for large and secondary text). The secondary button label takes the title colour. On Android the mappediconis tinted with the title colour too. - The primary button label is chosen against the button's own
backgroundColorwhen you set one (white or black, as for the title), whether or not the shield has a background. Without one, iOS keeps the system's white label on its own button; Android applies the same rule to its default button colour, so the label is white on the blue light-mode button and black on the light-blue dark-mode button.
These defaults colour the elements your config gives a text to. On iOS an
element you leave out entirely (no title, say) is drawn by the system with
its own text and colours; on Android the library draws every element, so the
blocked app's name as the default title follows the rule too.
A colour you set is always kept, readable or not. A translucent background
(#RRGGBBAA) is judged by its RGB alone: what shows through it differs by
platform (on iOS the blur over the blocked app, on Android nothing, the window
is opaque), so set the text colours yourself when you rely on translucency.
// Dark background, no text colours: white title, light grey subtitle,
// white labels on the blue button and for "Not now", in light and dark mode.
ExpoScreenTime.setShieldConfig({
backgroundColor: '#1a1a2e',
title: { text: 'App Blocked' },
subtitle: { text: 'This app is restricted during work hours' },
primaryButton: { text: 'OK', backgroundColor: '#4a4ae8' },
secondaryButton: { text: 'Not now' },
});setShieldConfigForActivity(activityName: string, config: ShieldConfig)
Shield appearance for a specific monitoring activity. When several block
sources cover the same app, the configuration is chosen by membership:
a blockOnThreshold block covering the app wins, then the schedule covering it
that started most recently, then the manual block (which uses the default
configuration), then the default configuration.
ExpoScreenTime.setShieldConfigForActivity('bedtime', {
title: { text: 'Time for Bed!' },
subtitle: { text: 'Apps are blocked until morning' },
backgroundColor: '#0d1b2a',
});clearShieldConfig()
Revert to the system default shield.
ExpoScreenTime.clearShieldConfig();Shield Actions
Requires the `ShieldActionExtension` target
setShieldActions(config: ShieldActionConfig)
Configure what the shield buttons do. Actions are 'close', 'unblock',
'defer', a snooze object or an open-app object — see
ShieldAction.
ExpoScreenTime.setShieldActions({
primaryAction: 'close',
secondaryAction: 'defer', // keep the shield up; the press is still recorded
});Actions:
'close'— close the blocked app; the block stays.'unblock'— lift the shield on this app in every source that shields it (the manual block and each schedule in progress), until a block is applied again (the nextblockSelection(),relock(), the next start of a monitored interval, or any full re-projection of the shields — a snooze press, a snooze ending). For an app shielded through its category, that category is lifted; for a web domain, that domain.'defer'— keep the shield on screen and let it redraw. The press is still recorded fordrainShieldInteractions().{ type: 'snooze', duration }— lift the shield on this app only, fordurationseconds of its use (a usage budget, liketemporaryUnlock), then shield it again. See Snooze below. The same grant from your app istemporaryUnlock(duration, { target }).{ type: 'openApp' }— bring your app forward, through a notification the user taps. See Open app below.
Up to 0.1.1, a native key mismatch made every configured action behave like
'close', and snooze behaved like 'close' until it was implemented.
Snooze
Pressing a snooze button lifts the shield on what was pressed — the app, the web domain, or, for an app shielded through its category, that category (iOS identifies such a shield by its category only) — and nothing else: every other shielded app stays shielded, and the sources covering the snoozed target stay active (a schedule in progress keeps its interval, its events and its shield configuration). The shield disappears and the user stays in the app they asked for; it does not close the app.
duration is a budget of seconds of use of that target, not wall-clock
time: it is spent only while the snoozed app is in the foreground, pauses when
the user leaves, and the target is shielded again — by whatever sources still
cover it — once the budget is spent, enforced by the DeviceActivityMonitor
extension even if your app never runs. Budgets below 30 seconds are raised to
30 (iOS usage thresholds are unreliable under that); consumption is reported
in ~30-second steps. Unspent budget expires at midnight. Use of the target
before the press does not count.
A snooze is exactly what
temporaryUnlock(duration, { target })
grants from your app — same record, same meter, same 30-second floor — so the
two replace each other on the same target, and everything below applies to
both.
Snoozes are independent of one another and of the whole-block
temporaryUnlock:
- Pressing snooze on a second app starts a second snooze with its own budget; the first keeps running. Pressing it again on the same target (for instance after its category was snoozed while the app is also shielded directly) — or granting a targeted unlock for it — restarts that target's budget.
- A whole-block
temporaryUnlockgranted while a snooze runs meters the snoozed app too; when the unlock's budget is spent, the snooze still in progress keeps its target lifted, and the other way round.isTemporarilyUnlocked()andgetRemainingUnlockSeconds()do not report snoozes. blockSelection(),unblockAll()andrelock()end every snooze.stopMonitoring()/stopAllMonitoring()and a schedule ending do not: a snooze outlives the source that was shielding its target, and still applies if another source shields it later that day.
Each snooze in progress occupies one of the 20 DeviceActivity slots iOS gives
an app (an internal activity, never listed by getMonitoredActivities) until
it is spent or the day ends. When no slot is free — 19 activities of yours
plus an unlock in progress, say — the press cannot arm a meter: the shield
stays and the app closes, like 'close'. Keep headroom if you rely on
snoozes.
ExpoScreenTime.setShieldActions({
primaryAction: 'close',
secondaryAction: { type: 'snooze', duration: 5 * 60 }, // 5 minutes of use
});Open app
iOS lets no extension launch an app, so an openApp press posts a local
notification; tapping it opens your app (the system's default, no handler to
write). getCapabilities().shieldOpenApp reports
"notification" so shared copy can say "tap Continue, then the notification".
The shield closes (the user lands on the Home screen with the banner on top).
The press is recorded for
drainShieldInteractions() like any
other, with the shielded target: once open, your app reads which app the
user wanted, and can temporaryUnlock
it or show its label.
ExpoScreenTime.setShieldConfig({
title: { text: "Take a breath" },
subtitle: { text: "Tap Continue, then the notification." },
primaryButton: { text: "Continue" },
secondaryButton: { text: "Close app" },
});
ExpoScreenTime.setShieldActions({
primaryAction: { type: "openApp" },
secondaryAction: "close",
});
// On foreground:
const intercept = ExpoScreenTime.drainShieldInteractions()
.filter((press) => press.button === "primary")
.at(-1);Posting needs the notifications permission step: request it with the
shieldOpenApp feature (see Permissions). Without
it, or if the notification cannot be posted, the press behaves like 'close'
— still recorded. The banner's title is the shield's title, else your app's
name; its body names your app and nothing else.
setShieldActionsForActivity(activityName: string, config: ShieldActionConfig)
Resolved like setShieldConfigForActivity:
threshold block, then latest schedule, then the default actions.
The buttons follow the screen: when iOS asks for a shield's appearance it
names the app and its category, while a button press names only one of
them. The appearance step records the source it resolved for each of those
tokens, and the button press reuses it as long as that source is still active
(a source suspended by temporaryUnlock never owns a shield). Two limits
remain: iOS caches shield appearances, so if the active sources change
without the shield being drawn again, the press resolves on its own, by token
membership; and the record for a category is shared by every app shielded
through that category, so the most recently drawn shield wins.
ExpoScreenTime.setShieldActionsForActivity('workHours', {
primaryAction: 'close',
// no secondary button for work hours
});clearShieldActions()
ExpoScreenTime.clearShieldActions();Android
On Android there is no system shield (see blocking): the library draws a full-screen Activity
over the blocked app and maps the stored ShieldConfig onto it with the same
precedence as iOS (the configuration of the source that owns the shield, else
the default: a threshold block, else the latest schedule covering the app,
else the manual block).
- Fields.
title,subtitle,primaryButton(text, colour, background colour) andsecondaryButtonmap one to one;backgroundColorfills the screen. Colours are#RRGGBBor#RRGGBBAA. What the config leaves out follows the system light or dark setting — except the text colours over abackgroundColoryou set, chosen for contrast against it like on iOS (default text colours), and the primary button's label, chosen the same way against whatever the button is painted in, the library's default blue included — and the title defaults to the blocked app's name with its icon, as the default iOS shield does. iconis an SF Symbol name on both platforms; Android maps this set to the equivalent Material Symbol and falls back to the blocked app's icon for any other name:hand.raised.fill,lock.fill,nosign,clock.fill,hourglass,moon.fill/moon.zzz.fill,exclamationmark.triangle.fill(and the unfilledhand.raised,lock,clock). The symbol is tinted with the title colour.backgroundBlurStyleis accepted and ignored: the shield is opaque, there is nothing behind it to blur.- Restriction targets (the uninstall dialog, the stores, the installer
under
denyAppRemoval()/denyAppInstallation()) draw the default configuration's colours and icon with the library's own texts, and honouropenApponly. - Buttons do what
setShieldActions/setShieldActionsForActivityconfigured for the owner, with the same precedence; the default, and Back, isclose(Home first, so the blocked app does not come back on its own). Every press is recorded fordrainShieldInteractions()with the app's handle astargetand the owning activity asactivityName(nullfor the manual block), collapsed per app within 2 s. Where the platforms differ:'unblock'lifts the app from every source shielding it, an allowlist included, and the shield simply goes: the user is in the app (iOS has to close it, a shield can only close or stay). The lift lasts until a block is applied again —blockSelection(),relock(),unblockAll(), a whole-blocktemporaryUnlock, a schedule starting or ending, a threshold firing, an unlock ending. A snooze on another app does not end it.{ type: 'snooze', duration }lifts the app fordurationseconds of its use, metered by the engine one second at a time (the 30 s floor and the midnight expiry hold), and the shield goes; the app is shielded again by itself once the budget is spent. Snoozes need no DeviceActivity slot: there is no limit on their number.{ type: 'openApp' }launches your app directly over the blocked one (shieldOpenApp: "direct"), no notification and no permission needed.'defer'keeps the shield up; the press is recorded.
- Behaviour. The shield is not in Recents, appears without animation and without a system splash (its first frame is already in the configured colour). In split-screen it covers the whole screen and keeps the split pair alive underneath (see blocking).