Skip to Content
expo-screen-time
API Reference

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 mapped icon is tinted with the title colour too.
  • The primary button label is chosen against the button's own backgroundColor when 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 next blockSelection(), 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 for drainShieldInteractions().
  • { type: 'snooze', duration } — lift the shield on this app only, for duration seconds of its use (a usage budget, like temporaryUnlock), then shield it again. See Snooze below. The same grant from your app is temporaryUnlock(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 temporaryUnlock granted 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() and getRemainingUnlockSeconds() do not report snoozes.
  • blockSelection(), unblockAll() and relock() 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) and secondaryButton map one to one; backgroundColor fills the screen. Colours are #RRGGBB or #RRGGBBAA. What the config leaves out follows the system light or dark setting — except the text colours over a backgroundColor you 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.
  • icon is 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 unfilled hand.raised, lock, clock). The symbol is tinted with the title colour.
  • backgroundBlurStyle is 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 honour openApp only.
  • Buttons do what setShieldActions / setShieldActionsForActivity configured for the owner, with the same precedence; the default, and Back, is close (Home first, so the blocked app does not come back on its own). Every press is recorded for drainShieldInteractions() with the app's handle as target and the owning activity as activityName (null for 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-block temporaryUnlock, 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 for duration seconds 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).

On this page