Skip to Content
expo-screen-time
API Reference

Report Templates

Both platforms

On iOS the report needs the DeviceActivityReportExtension target; on Android it needs the usageReports feature (on by default) and the usageAccess permission step. getCapabilities().usageReports says whether this build renders reports.

Compose the report screen's entire layout in JSX with Report.* components. The tree is serialized (never rendered by React) and rendered natively against the device's usage data — inside Apple's sandboxed report extension on iOS, by the module's own renderer from UsageEvents on Android. The layout comes from JS; the values never reach JavaScript on either platform.

import { DeviceActivityReport, Report } from 'expo-screen-time';

<DeviceActivityReport filterSegment="daily" style={{ height: 420 }}>
  <Report.VStack spacing={14} padding={16} alignment="leading">
    <Report.HStack spacing={14}>
      <Report.Gauge bind="totalDuration" goal={4 * 3600} size={64} color="#AF52DE" />
      <Report.VStack spacing={2} alignment="leading">
        <Report.Text text="SCREEN TIME" size={11} color="#8E8E93" letterSpacing={1} />
        <Report.Text bind="totalDuration" durationStyle="abbreviated" size={30} weight="bold" monospacedDigit />
        <Report.Text text="of 4h daily goal" size={12} color="#8E8E93" />
      </Report.VStack>
    </Report.HStack>
    <Report.ProgressBar bind="totalDuration" goal={4 * 3600} height={10} color="#AF52DE" />
    <Report.Chart type="area" bind="hourly" accentColor="#AF52DE" gradient height={90} showYAxis={false} />
    <Report.Divider />
    <Report.TopApps limit={3} spacing={10} emptyText="No app usage yet">
      <Report.HStack spacing={10}>
        <Report.AppIcon size={26} cornerRadius={6} />
        <Report.AppTitle size={14} />
        <Report.Spacer />
        <Report.Text bind="appDuration" durationStyle="short" size={13} monospacedDigit />
      </Report.HStack>
    </Report.TopApps>
  </Report.VStack>
</DeviceActivityReport>

The report is template-only: without a template (children or the imperative setReportTemplate), it renders a "No custom template set" placeholder.

Rules

  • Templates are descriptors, not React UI. Only Report.* components and hook-free compositions of them are allowed — React Native components can't render inside the extension, and hooks can't run during serialization. Both produce descriptive errors in development.
  • One template at a time. The native slot carries a single template — the last mounted templated report wins.
  • Size the container. The report can't report its content height back to React Native: the template is clipped to the component's style. Give it a height that fits your layout.
  • Display-only. No presses/callbacks from the report back to the app. Scrolling over the report is handled for you.
  • First render can be slow on iOS. The very first scene invocation after a fresh install (or freshly enabled Screen Time) can take up to a minute while iOS spins up its report service; subsequent renders are fast. Android reads the usage events in a few hundred milliseconds.
  • Not live. The data is read when the report mounts or its props change; remount it (a key) to refresh.

Bindings

bind props resolve to values computed natively from the report's usage data — JS only names them, it never sees them:

BindingScopeValue
totalDurationrootTotal screen time (seconds)
pickupsrootNumber of device pickups: every time the screen woke up, lock-screen glances included
longestActivityrootLongest continuous session (seconds)
appCountrootNumber of distinct apps used
firstPickuprootTime of the first pickup ("9:41 AM", or "—")
appDurationitemThe current app/category's usage (seconds)
appNameitemThe current app/category's display name
rankitem1-based position in the list

Pickups. A pickup is a screen wake, as Apple's Screen Time counts them: on Android every SCREEN_INTERACTIVE event in the window is one, whether or not the device was unlocked afterwards, and firstPickup is the first wake.

Categories on Android come from the category each developer declares in its manifest (ApplicationInfo.category: Game, Audio, Video, Image, Social, News, Maps, Productivity, Accessibility, with the system's localized title). Most apps declare none and land in "Other", so Android categories are coarse next to Apple's taxonomy.

Scopes. Root bindings work anywhere. Item bindings only work inside the per-item template of TopApps / Categories (a descriptive error is thrown otherwise).

Formatting durations. On Report.Text, durationStyle picks the format, the unit styles of Foundation's DateComponentsFormatter on iOS and of ICU's MeasureFormat on Android (the same data) in the device locale (en-US shown): 'abbreviated' (1h 24m), 'short' (1 hr, 24 min), 'full' (1 hour, 24 minutes). Under an hour only minutes show (24m, 24 min, 24 minutes). Alternatively format="percent" + goal renders any numeric binding as a percentage.

Weekly filter. With filterSegment="weekly", hourly chart buckets aggregate the week per hour-of-day (a daily usage profile, not a timeline), and duration bindings cover the whole week.

Layout components

Report.VStack / Report.HStack

Vertical / horizontal stack. Accepts all box props.

PropTypeDefaultDescription
spacingnumberSwiftUI default (~8)Points between children
alignment'leading' | 'center' | 'trailing' | 'top' | 'bottom''center'Cross-axis alignment: use leading/trailing in a VStack, top/bottom in an HStack
childrenReport.*—Stack content

Report.ZStack

Overlays its children. Accepts all box props.

PropTypeDefaultDescription
alignment'center' | 'topLeading' | 'topTrailing' | 'bottomLeading' | 'bottomTrailing''center'Where children anchor

Report.Grid

Fixed-column grid (LazyVGrid) — great for stat tiles. Accepts all box props.

PropTypeDefaultDescription
columnsnumber2Equal-width column count
spacingnumber8Points between cells (both axes)

Report.Spacer

Flexible space — pushes siblings apart inside a stack.

PropTypeDefaultDescription
minLengthnumber0Minimum size in points

Report.Divider

Horizontal hairline.

PropTypeDefaultDescription
colorstring (hex)system separatorLine color
thicknessnumberhairline (1px)Line height in points

Box props

Shared by VStack, HStack, ZStack and Grid:

PropTypeDefaultDescription
paddingnumber0Uniform padding (points)
paddingHorizontal / paddingVerticalnumber0Axis padding, additive with padding
backgroundColorstring (hex)transparentFill color
backgroundGradient[string, string]—Two-color gradient fill; overrides backgroundColor
gradientDirection'vertical' | 'horizontal' | 'diagonal''vertical'Gradient axis
cornerRadiusnumber0Rounds background and border
borderColor / borderWidthstring / number— / 0Stroked border following cornerRadius
shadowColorstring (hex, supports #RRGGBBAA)noneDrop shadow color
shadowRadius / shadowYnumber0 / 0Shadow blur / vertical offset
opacitynumber10–1
width / height / minHeightnumbercontent sizeFixed frame in points
fillWidthbooleanfalseStretch to the available width

Colors are hex strings: #RRGGBB or #RRGGBBAA.

Content components

Report.Text

A text element — static (text) or bound to a native value (bind). Exactly one of the two is required.

PropTypeDefaultDescription
textstring—Static content (string children work too)
bindbinding key—Native value to display (see Bindings)
durationStyle'abbreviated' | 'short' | 'full''abbreviated'Format for duration bindings
format'percent'—Render the binding as Math.round(value / goal * 100)%
goalnumber—Required with format="percent", in the binding's unit
sizenumber15Font size (points)
weight'light' | 'regular' | 'medium' | 'semibold' | 'bold' | 'heavy''regular'Font weight
design'default' | 'rounded' | 'serif' | 'monospaced''default'Font design (rounded = SF Rounded)
colorstring (hex)label colorText color
opacitynumber10–1
italic / underline / strikethroughbooleanfalseDecorations
uppercasebooleanfalseUppercases the resolved text
monospacedDigitbooleanfalseTabular figures — keeps bound numbers from jiggling
lineLimitnumber1Max lines
letterSpacingnumber0Kerning in points
align'leading' | 'center' | 'trailing'—Multiline alignment; also stretches to available width

Report.Symbol

An SF Symbol. On Android a bundled Material Symbol stands in for a documented set of names: hourglass, hourglass.bottomhalf.filled, clock, clock.fill, timer, calendar, chart.bar, chart.bar.fill, chart.pie, chart.pie.fill, apps.iphone, square.grid.2x2, iphone, hand.raised, hand.raised.fill, lock, lock.fill, nosign, moon.fill, moon.zzz.fill, exclamationmark.triangle.fill, checkmark.circle, checkmark.circle.fill, star, star.fill, bell, bell.fill, eye, eye.fill, arrow.up, arrow.down, gamecontroller, gamecontroller.fill, questionmark. Any other name leaves an empty slot of size on Android, so the layout around it holds. renderingMode and weight are iOS-only (Android tints the glyph).

PropTypeDefaultDescription
namestringrequiredSF Symbol name (e.g. "hourglass")
sizenumber17Point size
colorstring (hex)label colorTint
weightfont weight'regular'Symbol weight
renderingMode'monochrome' | 'hierarchical''monochrome'hierarchical renders multi-level symbols with depth
opacitynumber10–1

Report.Chart

A Swift Charts plot of usage data.

PropTypeDefaultDescription
type'bar' | 'line' | 'area' | 'pie'requiredMark type. pie needs iOS 17 (falls back to bar); every type renders on Android
bind'hourly' | 'topApps' | 'categories'requiredData series: 24 hour-of-day buckets, or per-app/per-category totals
accentColorstring (hex)blueSeries color
colorPalettestring[]—Per-entry colors (bar/pie with list binds); cycles when shorter
gradientbooleanfalseVertical fade of the accent color (bar/area)
barCornerRadiusnumber0Rounded bar marks
lineWidthnumber2Line chart stroke width
showPointsbooleanfalseLine charts: a point at each value
averageLinebooleanfalseDashed rule at the series average
goalValuenumber—Solid-dash goal rule, in minutes (chart Y unit)
goalColorstring (hex)redGoal rule color
pieInnerRadiusnumber0.55Donut hole ratio 0–1 (0 = solid pie)
labelColorstring (hex)secondary labelAxis label color
heightnumber120Chart height (points)
showXAxisbooleanfalse for hourly, else trueX-axis labels/grid
showYAxisbooleantrueY-axis labels/grid
xAxisStridenumber6Hourly X-axis: label every N hours
maxItemsnumber6Max entries for topApps/categories binds

Report.ProgressBar

Linear progress toward a goal: bind / goal, clamped to 0–1.

PropTypeDefaultDescription
bindbinding keytotalDurationNumeric binding
goalnumberrequiredIn the binding's unit (seconds for durations, count for pickups)
heightnumber8Bar height (points)
colorstring (hex)blueFill
trackColorstring (hex)quaternary fillTrack
cornerRadiusnumberheight / 2Capsule by default

Report.Gauge

Progress toward a goal as a SwiftUI Gauge.

PropTypeDefaultDescription
bindbinding keytotalDurationNumeric binding
goalnumberrequiredIn the binding's unit
style'circular' | 'linear''circular'Circular ring with a % label, or a slim capacity bar
sizenumber56Circular diameter in points — any size works, the ring is scaled internally
colorstring (hex)blueTint

Item lists

Report.TopApps / Report.Categories

Repeats their children once per app / category (sorted by usage, descending). Inside, the item scope enables appDuration / appName / rank bindings and the AppIcon / AppTitle components.

PropTypeDefaultDescription
limitnumber5Max rows
spacingnumber8Points between rows
emptyTextstring—Shown when there is no usage data yet
childrenReport.*requiredThe per-item template

Report.AppIcon

The current item's real app/category icon: on iOS rendered from the opaque token via Label(token) (only possible inside the sandbox), on Android the app's launcher icon from the package manager. Android categories have no icon and show a category glyph on the placeholder fill. Item scope only.

PropTypeDefaultDescription
sizenumber28Icon size (points)
cornerRadiusnumber0Clip radius

Report.AppTitle

The current item's display name. Item scope only.

PropTypeDefaultDescription
sizenumber15Font size
weightfont weight'regular'Font weight
colorstring (hex)label colorText color
opacitynumber10–1
lineLimitnumber1Max lines
<Report.Categories limit={4} emptyText="Nothing yet">
  <Report.HStack spacing={8}>
    <Report.AppIcon size={22} />
    <Report.AppTitle size={13} />
    <Report.Spacer />
    <Report.Text bind="appDuration" durationStyle="short" size={12} />
  </Report.HStack>
</Report.Categories>

Imperative API

The children API above is the reactive path and should be preferred. For cases where the template is set outside a render (e.g. app startup config):

import { setReportTemplate, clearReportTemplate, Report } from 'expo-screen-time';

setReportTemplate(
  <Report.VStack padding={16}>
    <Report.Text bind="totalDuration" durationStyle="abbreviated" size={32} weight="bold" />
  </Report.VStack>
);
// Any mounted <DeviceActivityReport> without children renders it.

clearReportTemplate(); // back to the placeholder

Platform notes

The same template JSON is rendered by SwiftUI on iOS and by Android views on Android, with the same bindings, units, defaults and copy. Where the platforms differ:

  • Fonts. design="rounded" has no Android face and renders as the default sans-serif; serif and monospaced are the system ones.
  • Shadows. shadowY has no Android counterpart; the elevation's own offset stands in.
  • Symbols. See Report.Symbol for the names Android renders.
  • Categories and pickups. See Bindings.
  • Without usage access (the usageAccess permission step) the Android report renders zeros, as iOS does without Screen Time authorization.

Versioning

The serialized template carries a version; a native side older than the JS falls back to the placeholder (and unknown components/props are skipped) — templates degrade, they don't crash.

On this page