When to use it. One number, told whole: the value large with its unit, a change arrow and percent against a reference, a background tinted by the threshold band the value sits in, and a faint sparkline of recent values under it. The one-control replacement for a label + sparkline + status light stacked by hand. Read-only.
Type
statTile
Also titled
Stat Tile
Default size
3 rows × 2 columns
Symbol
number.square
Docs
Docs complete
Search for it as
kpi
metric
stat
number
counter
big number
Rendered by the app
Fields
21 fields you can set on a statTile control. Every control also takes the shared fields (id, position, span, sync, action).
Fields
Field
Type
Default
What it does
Titlelabel
text
—
The caption above the number
Shows this text as the tile's title in the title text size.
hideLabelhideLabel
on / off
false(off)
Number without a caption
Removes the title line when on, leaving the number alone.
Unitunit
text
—
What the number is measured in
Shows the unit small beside the number in the viewer's local unit, e.g. celsius reads \u00b0F in the US.
Number sizevalueSize
number14–80 ptstep 1
34
How big the number is
Sets the big number's size from 14 to 80 points.
Number formatformatValue
text
—
How the number is written
Formats the big number, e.g. decimal:1 shows 72.5 and decimal:0 shows 73.
Decimal placesstep
number
—
How many digits after the point
Rounds the number when no format is set, e.g. 1 shows 72.5 and 0 shows 73.
History lengthsparklinePoints
number5–500step 5
50
How far back the faint trend reaches
Keeps the last 5 to 500 readings in the trend line; more points show a longer history.
Line widthlineWidth
number0.5–12 ptstep 0.5
2
How thick the trend line is
Sets the trend line stroke from 0.5 to 12 points.
Colortint
color
—
The trend line color
Paints the faint trend line in one color when there are no color zones.
GlowglowRadius
number0–30 ptstep 1
0
A soft halo around the trend line
Adds a glow behind the trend line from 0 (off) to 30 points wide.
Line endslineCap
choiceone of 3
round
The shape of the trend line's ends
Rounds, flattens or squares the two ends of the trend line.
rounddefaultsoft rounded ends
buttflat ends cut exactly at the data point
squareflat ends that stick out half a stroke past the data point
hideBackgroundhideBackground
on / off
false(off)
The card behind the number
Removes the card fill and its zone tint when on so the number floats on the layout.
Motionanimation
choiceone of 5
—
How the number moves when it changes
The number rolls to each new value; instant swaps it with no roll.
smoothan even roll and the default
snappya quick roll that settles fast
bouncyovershoots slightly then springs back
gentlea slow and soft roll
instantswaps straight to the new number with no roll
Compare againststatTileConfig.reference
number
—
The number to compare with
Sets the baseline in the tile's unit; the arrow and change show the value minus this.
Live reference pathstatTileConfig.referencePath
text
—
Where a live comparison number comes from
Reads the baseline from this dot path in the same data as the value and replaces Compare against once it arrives.
Change shown asstatTileConfig.deltaMode
choiceone of 2
percent
How the change is written
Shows the change as a percent of the baseline or as the plain difference in the tile's unit.
percentdefaultchange as a percent of the baseline
absolutechange as the plain difference in the value's unit
Up is badstatTileConfig.invertDelta
on / off
false(off)
Swap good and bad colors
When on a rise is drawn red and a fall green instead of the reverse.
Color zonesstatTileConfig.thresholds
list
—
Background colors for different ranges of values
Tints the card with the color of the zone the value sits in, e.g. green to 250 then amber to 600 then red.
Critical at or abovestatTileConfig.criticalAbove
number
—
The value where the tile turns solid
At or above this value the whole tile fills solid with its zone color and white text.
Critical at or belowstatTileConfig.criticalBelow
number
—
The low value where the tile turns solid
At or below this value the whole tile fills solid with its zone color and white text.
Show trendstatTileConfig.showSparkline
on / off
true(on)
The faint trend under the number
Draws the recent-history line under the number when on and hides it when off.
Emits and receives
What this control sends when you use it, and what it can show or follow when data arrives.
Receives
Receives
Takes
From
Type
What it does
valueshow
hub, mqtt, http, sensor, store, derive, default
number
a number to show large, or a list of numbers that becomes the trend and shows its last point
the number updates and joins the faint trend under it; a list replaces the trend
Example: 40
Sample
The placeholder value the editor shows before real data arrives.
40 then 75
Examples
11 examples, each one a control you can paste into a layout.
Demonstrates referencePath, invertDelta and criticalAbove: the baseline arrives with the value, a rise reads red, and at 600 ms or more the whole tile fills solid red.
The tile listens like a gauge: its sync delivers a number. Each number also appends to the tile's rolling history (the same buffer a Title uses, capped at sparklinePoints); a numeric array replaces the history and the number shows its last point.
Delta = value − reference. Percent mode divides by |reference|; a missing reference — or a zero one in percent mode — hides the delta rather than showing ∞ or NaN. A change that rounds to 0.0% shows a flat arrow in the muted colour.
Colour: up is good (green) and down is bad (red) unless invertDelta flips them.
Thresholds: sorted by limit, the value takes the first band whose limit it does not exceed; below the first → the first band, above the last → the last. The tint is soft by default; criticalAbove/criticalBelow switch it to a solid fill.
Behavior
The number rolls with the native numeric-text transition (via the shared numeric readout); the band tint cross-fades.
Tapping does nothing — the tile is display-only. Add a longPressGroup for detail.
VoiceOver reads the title, the value with its unit, and "up 12.4%" / "down" / "unchanged".