When to use it. One SF Symbol with native rendering modes, variable layers, and configurable animation effects, including custom rain, snow, and sparkles. Effects run locally without a stream of server updates. The symbol's own annotations determine which parts move: for example, rotate with byLayer spins a desk fan's blades while its housing stays still.
Type
symbol
Default size
2 rows × 2 columns
Symbol
cloud.bolt.rain.fill
Docs
Docs complete
Search for it as
icon
sf symbol
glyph
emoji
shape
picture
Rendered by the app
Fields
29 fields you can set on a symbol control. Every control also takes the shared fields (id, position, span, sync, action).
Fields
Field
Type
Default
What it does
SymbolsystemName
text
—
Which icon to show
Draws this SF Symbol as the main glyph; a synced text value can swap it live.
Titlelabel
text
—
The caption under the icon
Shows this text under the glyph.
Title shownhideLabel
on / off
false(off)
Hide the caption
Turned on, the caption under the glyph is not shown.
Colortint
color
—
The icon's color
Colors the glyph; multicolor symbols keep their own colors instead.
GlowglowRadius
number0–30 ptstep 1
0
A soft glow behind the icon
Adds a blurred halo of the glyph's own color behind it, 0 for none up to 30 points.
BackgroundhideBackground
on / off
false(off)
Remove the card behind it
Turned on, the glass card is removed and the icon floats on the page.
colorMapcolorMap
object
—
Show different colors for different values
Tints the glyph with the hex color listed for the incoming value.
haptichaptic
choiceone of 10
—
Buzz when tapped
Plays this haptic feedback each time the symbol is tapped; light when not set.
noneno haptic
lighta small light tap and the default
mediuma medium tap
heavya strong tap
softa rounded cushioned tap
rigida sharp firm tap
selectiona tiny tick like scrolling a picker
successa success pattern
warninga warning pattern
erroran error pattern
ColouringsymbolConfig.renderingMode
choiceone of 4
monochrome
How the icon is colored
Chooses how the symbol's layers take color.
monochromedefaultone color for the whole glyph and the default
hierarchicallayers shaded from one color, strongest first
paletteeach layer gets its own color from the palette list
multicolorthe symbol's own built-in colors and ignores the tint
palettesymbolConfig.palette
list
—
A color for each icon layer
Colors the symbol's layers in order, primary first, when the colouring is palette.
WeightsymbolConfig.weight
choiceone of 9
regular
How thick the icon lines are
Sets the stroke thickness of the glyph.
ultraLightthe thinnest lines
thinvery fine lines
lightfine lines
regulardefaultnormal lines and the default
mediumslightly heavier lines
semiboldfairly heavy lines
boldheavy lines
heavyvery heavy lines
blackthe heaviest lines
VariantsymbolConfig.variant
choiceone of 6
none
An outline or badge style
Applies a variant to the symbol name, such as a circle around it or a slash through it.
nonedefaultthe symbol exactly as named and the default
fillthe filled version
circlethe glyph inside a circle
squarethe glyph inside a square
rectanglethe glyph inside a rectangle
slasha diagonal slash through the glyph
SizesymbolConfig.size
number12–300step 1
—
How big the icon is
Sets the glyph's point size; left empty it scales to fill the cell.
EffectsymbolConfig.effect
choiceone of 11
none
An animation that keeps playing
Loops an animation on the glyph, either one of Apple's symbol effects or CAR-TER's own particles.
nonedefaultno animation and the default
rainslanted drops falling below the symbol
snowflakes falling and drifting below the symbol
sparklefour-point stars twinkling around the symbol
pulsethe icon fades in and out
breathethe icon gently grows and shrinks
variableColorthe icon's layers light up in sequence
rotatethe icon spins
wigglethe icon shakes to get attention
bouncethe icon hops
scalethe icon is held larger or smaller
particleColorsymbolConfig.particleColor
color
—
Color of the rain, snow or sparkles
Overrides the color of the custom particles instead of the tint or palette.
particleIntensitysymbolConfig.particleIntensity
number0–1step 0.05
0.65
How much rain, snow or sparkle
Sets how dense the particles are from 0 to 1, with 0 hiding them.
particleAnglesymbolConfig.particleAngle
number-60–60step 1
-18
Which way the rain or snow falls
Tilts falling particles from straight down, negative toward the left and positive toward the right.
effectOptionssymbolConfig.effectOptions
list
—
Extra settings for the animation
Adds Apple's modifiers such as byLayer, clockwise or iterative to a native effect.
loopsymbolConfig.loop
choiceone of 3
continuous
How often the animation repeats
Chooses whether the effect repeats forever, repeats with pauses, or plays a single time.
continuousdefaultrepeats without stopping and the default
periodicplays, waits the loop delay, then plays again
onceplays one time and stops
loopCountsymbolConfig.loopCount
number1–100step 1
—
How many times it plays
With periodic looping, stops the effect after this many plays; empty means forever.
loopDelaysymbolConfig.loopDelay
number0–30step 0.1
1
Pause between plays
With periodic looping, waits this many seconds between plays.
speedsymbolConfig.speed
number0.1–5step 0.1
1
How fast it animates
Multiplies the animation speed; 2 plays twice as fast and 0.5 half as fast.
activeWhensymbolConfig.activeWhen
text
always
When the animation runs
Plays the effect always, only when the synced value is true, or only when it equals the state word you give.
variableMinsymbolConfig.variableMin
number
0
Number where the icon is empty
The synced number at which the symbol's variable layers show as empty.
variableMaxsymbolConfig.variableMax
number
100
Number where the icon is full
The synced number at which the symbol's variable layers show as full.
transitionsymbolConfig.transition
choiceone of 6
—
How the icon changes to a new one
Animates the swap when the glyph changes to a different symbol.
replacethe old glyph morphs into the new one and the default
replace.downUpthe old glyph slides down and the new one comes up
replace.upUpboth glyphs move up
replace.offUpthe old glyph fades while the new one moves up
replace.magicmatching parts of the two glyphs morph into each other
noneswaps instantly with no animation
tapEffectsymbolConfig.tapEffect
choiceone of 7
none
A little animation on tap
Plays this effect once each time the symbol is tapped.
nonedefaultno animation and the default
bouncethe icon hops once
pulsethe icon fades once
variableColorthe layers light up once in sequence
wigglethe icon shakes once
rotatethe icon spins once
breathethe icon grows and shrinks once
triggerssymbolConfig.triggers
list
—
Events that play the symbol effect once
Plays a one-shot effect each time a matching server event arrives.
symbolConfigsymbolConfig
object
—
The animation and look settings bundle
Holds the rendering, effect, particle, loop and tap settings below; leave it out for a still symbol.
Theme fields
Restyle one control by setting these in its theme object; a layout's theme sets them for every control.
Theme fields
Field
Type
Default
What it does
foregroundColortheme.foregroundColor
color
#FFFFFF
The caption color
Colors the caption text under the glyph.
Emits and receives
What this control sends when you use it, and what it can show or follow when data arrives.
Emits
Emits
Sends
When
Type
What it sends
When you tap the symbolvalue
tap
string
the name of the symbol being shown
Example: Sample A
Receives
Receives
Takes
From
Type
What it does
valueshow
hub, mqtt, http, store, default
string
a symbol name to show, a state word to match, or a number that fills the symbol
the symbol swaps, tints or fills to match it, and plays its effect when active
Example: Sample A
Sample
The placeholder value the editor shows before real data arrives.
true
Examples
10 examples, each one a control you can paste into a layout.
This is .symbolEffect(.variableColor.iterative.dimInactiveLayers, options:
.repeating) on a multicolor image: eligible layers change opacity in sequence.
Inactive layers stay faintly visible so the icon does not disappear during the
cycle. Use hideInactiveLayers to hide them instead. The exact layers depend on
Apple's symbol annotations. This is not travelling rain.
.wiggle.byLayer with .repeat(.continuous) applies the standard wiggle effect.
It is not a workout movement or running cycle. activeWhen ties the effect to
the synced state — it runs while the workout is on.
Download SF Symbols for Mac, select a
symbol, and open the Animation inspector in the right sidebar. Choose an
effect, its layer/direction options, and a repeat mode, then press Preview.
The inspector's Copy menu provides the corresponding code. Apple's
Animate symbols in your app
and What's new in SF Symbols 6
walk through the APIs and per-layer animation.
The Animation examples menu in this page's live preview loads the examples
below, including their symbol, colours, effect, and repeat settings. Numeric
variable-layer input is optional; leave it off to preview the full symbol.
Rain and workout figures:variableColor changes layer opacity; it does not
make raindrops travel diagonally. wiggle.byLayer uses the symbol's annotated
motion groups; it does not provide a running gait or an arbitrary joint animation.
Apple's public symbol effects do not expose a general “play this symbol's real-world
activity” API. Matching bespoke Weather or Workout app motion requires separately
authored animation. CAR-TER adds its own rain, snow, and sparkle effects,
described below. Running figures are not included.
Effects
Looping effects (effect) take the modifiers Apple gives them, spelled exactly
as in Swift — effect: "variableColor" with effectOptions: ["iterative",
"hideInactiveLayers"] is .symbolEffect(.variableColor.iterative.hideInactiveLayers,
options: .repeat(.continuous)). byLayer uses the motion groups annotated in
the symbol; it does not automatically separate every visible shape or limb.
Open a symbol in the SF Symbols app → Animation to preview the result. Put
supported modifier names into the effectOptions list.
Attention shake using the symbol's annotated motion groups
scale
up, down, byLayer, wholeSymbol
Held larger / smaller while active
bounce
up, down, byLayer, wholeSymbol
Discrete in iOS, so it loops as periodic
Variable colour is layer sequencing, not a particle engine: the drops light up
in Apple's order, they do not travel. hideInactiveLayers blanks inactive layers
outright; on a symbol whose every layer is variable that includes the cloud for
an instant each cycle — the SF Symbols app preview shows you which.
One-shot effects (tapEffect, triggers[].effect): bounce, pulse,
variableColor, wiggle, rotate, breathe. A trigger is registered exactly
like a group Pulse: name the event (broadcast for the shared channel),
optionally a filter, and the effect plays each time a matching frame lands.
Reduce Motion silences every effect, and a resident-but-hidden layout stops
the loop, so a decorative cloud never costs battery nobody can see.
Custom particle effects
Set symbolConfig.effect to rain, snow, or sparkle. These are CAR-TER
animations rendered with SwiftUI Canvas; they are not extra Apple symbol presets.
rain: slanted drops falling below the symbol.
snow: small flakes falling and drifting below the symbol.
sparkle: four-point stars twinkling around the symbol.
particleIntensity sets density from 0 to 1. particleAngle sets rain/snow
direction from -60° (left) to 60° (right). particleColor overrides particle
colour; otherwise palette mode uses its second colour, multicolor uses blue rain,
white snow, or yellow sparkles, and other modes use the control's tint.
For ordinary cloud.rain, cloud.drizzle, cloud.heavyrain, cloud.snow,
cloud.sleet, and cloud.hail names, including .fill, rain/snow use a plain
cloud and replace static precipitation with particles. cloud.sun.rain,
cloud.moon.rain, and cloud.bolt.rain retain their sun, moon, or bolt.
Other glyphs, including circle variants, remain intact and gain particles.
The synced name and the name sent by a tap action stay unchanged.
speed, activeWhen, loop, loopDelay, and loopCount work with custom
effects. One base cycle lasts 1.4 seconds for rain, 3.2 for snow, or 1.8 for
sparkles, divided by speed. once plays one cycle; periodic fades particles
between cycles and waits the specified delay (seconds, unaffected by speed).
Completed finite effects hide their particles and stop refreshing.
Reduce Motion, inactive apps, hidden layouts, and a false activeWhen stop the
clock and show static particles. Re-enabling the effect starts a fresh cycle.
Zero intensity also stops refreshing. Native tapEffect and trigger effects can
still animate the glyph; custom particles are currently looping effects only.
effectOptions applies only to native effects.
SF Symbols are built from up to three palette layers, and palette colours
them in order (cloud.rain.fill = cloud, drops; moon.stars.fill = moon,
stars). multicolor uses Apple's own annotation instead — a white cloud, blue
drops, a yellow bolt — and is the natural pairing for weather. To learn a
symbol's layer order, give it renderingMode: "palette" with three loud colours
once, or read it off the SF Symbols app in Palette rendering.
What the synced value does
A string picks the glyph: an iconMap hit, or — when it names a real
symbol — the symbol itself, so a server can push "cloud.bolt.rain.fill".
A state word can also gate the loop through activeWhen.
A number fills the symbol's variable layers (wifi, speaker.wave.3,
cloud.rain, rainbow …) over variableMin…variableMax.
A bool gates the loop with activeWhen: "truthy".
Behavior
The glyph scales to its cell like an Background and never below ~28pt; in a
flow grid set controlHeight (or symbolConfig.size) for a bigger tile —
see Grid Dimensions
An unknown symbol name renders a dashed placeholder rather than a blank tile
Tap fires the action with {{value}} = the symbol name shown, plus
tapEffect and the haptic
multicolor ignores tint; palette reads symbolConfig.palette, repeating
its last entry for any missing layer, and falls back to tint
With a numeric value, transition defaults to none: a replace transition on
a ramping variable value re-renders every tick (measured, see the reel notes)
Related
Background — pictures with a symbol fallback and the same value maps
Pulse — the group-level event ring triggers are modelled on