Guide / Controls / Readouts

Symbol

An icon that can animate

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
Symbol: Moving rain — custom particles
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
FieldTypeDefaultWhat it does
SymbolsystemNametext—

Which icon to show

Draws this SF Symbol as the main glyph; a synced text value can swap it live.

Titlelabeltext—

The caption under the icon

Shows this text under the glyph.

Title shownhideLabelon / offfalse (off)

Hide the caption

Turned on, the caption under the glyph is not shown.

Colortintcolor—

The icon's color

Colors the glyph; multicolor symbols keep their own colors instead.

GlowglowRadiusnumber0–30 ptstep 10

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.

BackgroundhideBackgroundon / offfalse (off)

Remove the card behind it

Turned on, the glass card is removed and the icon floats on the page.

colorMapcolorMapobject—

Show different colors for different values

Tints the glyph with the hex color listed for the incoming value.

haptichapticchoiceone 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.renderingModechoiceone of 4monochrome

How the icon is colored

Chooses how the symbol's layers take color.

  • monochrome defaultone 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.palettelist—

A color for each icon layer

Colors the symbol's layers in order, primary first, when the colouring is palette.

WeightsymbolConfig.weightchoiceone of 9regular

How thick the icon lines are

Sets the stroke thickness of the glyph.

  • ultraLightthe thinnest lines
  • thinvery fine lines
  • lightfine lines
  • regular defaultnormal lines and the default
  • mediumslightly heavier lines
  • semiboldfairly heavy lines
  • boldheavy lines
  • heavyvery heavy lines
  • blackthe heaviest lines
VariantsymbolConfig.variantchoiceone of 6none

An outline or badge style

Applies a variant to the symbol name, such as a circle around it or a slash through it.

  • none defaultthe 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.sizenumber12–300step 1—

How big the icon is

Sets the glyph's point size; left empty it scales to fill the cell.

EffectsymbolConfig.effectchoiceone of 11none

An animation that keeps playing

Loops an animation on the glyph, either one of Apple's symbol effects or CAR-TER's own particles.

  • none defaultno 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.particleColorcolor—

Color of the rain, snow or sparkles

Overrides the color of the custom particles instead of the tint or palette.

particleIntensitysymbolConfig.particleIntensitynumber0–1step 0.050.65

How much rain, snow or sparkle

Sets how dense the particles are from 0 to 1, with 0 hiding them.

particleAnglesymbolConfig.particleAnglenumber-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.effectOptionslist—

Extra settings for the animation

Adds Apple's modifiers such as byLayer, clockwise or iterative to a native effect.

loopsymbolConfig.loopchoiceone of 3continuous

How often the animation repeats

Chooses whether the effect repeats forever, repeats with pauses, or plays a single time.

  • continuous defaultrepeats without stopping and the default
  • periodicplays, waits the loop delay, then plays again
  • onceplays one time and stops
loopCountsymbolConfig.loopCountnumber1–100step 1—

How many times it plays

With periodic looping, stops the effect after this many plays; empty means forever.

loopDelaysymbolConfig.loopDelaynumber0–30step 0.11

Pause between plays

With periodic looping, waits this many seconds between plays.

speedsymbolConfig.speednumber0.1–5step 0.11

How fast it animates

Multiplies the animation speed; 2 plays twice as fast and 0.5 half as fast.

activeWhensymbolConfig.activeWhentextalways

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.variableMinnumber0

Number where the icon is empty

The synced number at which the symbol's variable layers show as empty.

variableMaxsymbolConfig.variableMaxnumber100

Number where the icon is full

The synced number at which the symbol's variable layers show as full.

transitionsymbolConfig.transitionchoiceone 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.tapEffectchoiceone of 7none

A little animation on tap

Plays this effect once each time the symbol is tapped.

  • none defaultno 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.triggerslist—

Events that play the symbol effect once

Plays a one-shot effect each time a matching server event arrives.

symbolConfigsymbolConfigobject—

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
FieldTypeDefaultWhat it does
foregroundColortheme.foregroundColorcolor#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
SendsWhenTypeWhat it sends
When you tap the symbolvaluetapstring

the name of the symbol being shown

Example: Sample A

Receives

Receives
TakesFromTypeWhat it does
valueshowhub, mqtt, http, store, defaultstring

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.

Moving rain — custom particles

JSON 9 lines
{
  "type": "symbol", "id": "rain", "position": [0, 0], "span": [2, 2],
  "systemName": "cloud.rain.fill", "label": "Rain", "tint": "#8AA5BD",
  "defaultValue": true,
  "symbolConfig": {
    "effect": "rain", "particleColor": "#3DA9FC", "particleAngle": -22,
    "particleIntensity": 0.65, "activeWhen": "truthy"
  }
}

Open in CAR-TER

Symbol: Moving rain — custom particles
Rendered by the app

Drifting snow — custom particles

JSON 5 lines
{
  "type": "symbol", "id": "snow", "position": [0, 2], "span": [2, 2],
  "systemName": "cloud.snow.fill", "label": "Snow", "tint": "#8AA5BD",
  "symbolConfig": { "effect": "snow", "particleColor": "#68BBDD", "particleAngle": 8 }
}

Open in CAR-TER

Symbol: Drifting snow — custom particles
Rendered by the app

Sparkling favourite — custom particles

JSON 5 lines
{
  "type": "symbol", "id": "sparkle", "position": [2, 0], "span": [2, 2],
  "systemName": "star.fill", "label": "Favourite", "tint": "#E6A323",
  "symbolConfig": { "effect": "sparkle", "particleColor": "#E6A323", "tapEffect": "bounce" }
}

Open in CAR-TER

Symbol: Sparkling favourite — custom particles
Rendered by the app

Fan — blades on their hub

JSON 10 lines
{
  "type": "symbol",
  "id": "fan",
  "position": [2, 2],
  "span": [2, 2],
  "systemName": "fan.desk.fill",
  "label": "Fan",
  "tint": "#8E8E93",
  "symbolConfig": { "renderingMode": "hierarchical", "effect": "rotate", "effectOptions": ["clockwise", "byLayer"], "speed": 1.5 }
}

Open in CAR-TER

Symbol: Fan — blades on their hub
Rendered by the app

Rain — cycling layer opacity

JSON 13 lines
{
  "type": "symbol",
  "id": "rain",
  "position": [0, 0],
  "span": [2, 2],
  "systemName": "cloud.rain.fill",
  "label": "Rain",
  "symbolConfig": {
    "renderingMode": "multicolor",
    "effect": "variableColor",
    "effectOptions": ["iterative", "dimInactiveLayers"]
  }
}

Open in CAR-TER

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.

Symbol: Rain — cycling layer opacity
Rendered by the app

Workout figure — native wiggle

JSON 12 lines
{
  "type": "symbol",
  "id": "hiit",
  "position": [0, 2],
  "span": [2, 2],
  "systemName": "figure.highintensity.intervaltraining",
  "label": "Training",
  "tint": "#30D158",
  "defaultValue": true,
  "symbolConfig": { "effect": "wiggle", "effectOptions": ["byLayer"], "activeWhen": "truthy" },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "workout" }, "valuePath": "active" }]
}

Open in CAR-TER

.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.

Symbol: Workout figure — native wiggle
Rendered by the app

Storm with a server-fired strike

JSON 17 lines
{
  "type": "symbol",
  "id": "storm",
  "position": [2, 0],
  "span": [2, 2],
  "systemName": "cloud.bolt.rain.fill",
  "label": "Storm",
  "symbolConfig": {
    "renderingMode": "multicolor",
    "effect": "variableColor",
    "effectOptions": ["iterative"],
    "speed": 1.4,
    "triggers": [
      { "event": "broadcast", "filter": { "msg_type": "weather", "alert": "lightning" }, "effect": "bounce" }
    ]
  }
}

Open in CAR-TER

Symbol: Storm with a server-fired strike
Rendered by the app

Signal strength — a number fills the bars

JSON 12 lines
{
  "type": "symbol",
  "id": "signal",
  "position": [2, 0],
  "span": [2, 2],
  "systemName": "wifi",
  "label": "Wi-Fi",
  "tint": "#30D158",
  "defaultValue": 72,
  "symbolConfig": { "renderingMode": "hierarchical", "variableMin": 0, "variableMax": 100 },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "net" }, "valuePath": "rssi_pct" }]
}

Open in CAR-TER

Symbol: Signal strength — a number fills the bars
Rendered by the app

Alert that wiggles only while armed

JSON 12 lines
{
  "type": "symbol",
  "id": "armed",
  "position": [2, 2],
  "span": [2, 2],
  "systemName": "exclamationmark.triangle.fill",
  "label": "Alarm",
  "tint": "#FF9F0A",
  "defaultValue": true,
  "symbolConfig": { "effect": "wiggle", "loop": "periodic", "loopDelay": 1.5, "activeWhen": "truthy" },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "alarm" }, "valuePath": "armed" }]
}

Open in CAR-TER

Symbol: Alert that wiggles only while armed
Rendered by the app

Tap to like

JSON 11 lines
{
  "type": "symbol",
  "id": "like",
  "position": [4, 0],
  "span": [2, 2],
  "systemName": "heart.fill",
  "tint": "#FF375F",
  "hideBackground": true,
  "symbolConfig": { "tapEffect": "bounce" },
  "action": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "like", "symbol": "{{value}}" } }
}

Open in CAR-TER

Symbol: Tap to like
Rendered by the app

Try it on your phone

carterkit serves a small hub on your computer and pushes one example to CAR-TER on your iPhone or iPad. Pair once with the code it prints.

  1. Install the Python kit.

    pip install carterkit
  2. Show “Moving rain — custom particles” on your phone.

    carterkit demo symbol --example 'Moving rain — custom particles'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Finding Apple's animations

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.

Effect Modifiers Reads as
variableColor iterative, cumulative, reversing, nonReversing, hideInactiveLayers, dimInactiveLayers The symbol's annotated layers sequence — raindrops cycling, a signal sweeping, bars filling
pulse byLayer, wholeSymbol Opacity breathing
breathe plain, pulse, byLayer, wholeSymbol Gentle grow-and-shrink
rotate clockwise, counterClockwise, byLayer, wholeSymbol Spinning — byLayer turns a fan.fill's blades on their own hub; wholeSymbol turns a sun
wiggle up, down, left, right, forward, backward, clockwise, counterClockwise, byLayer, wholeSymbol 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.

The approach is inspired by Kieran Brown's raining-cloud example and Vortex's particle presets. CAR-TER's implementation is original and adds no package dependency.

Layers and colours

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)
  • Background — pictures with a symbol fallback and the same value maps
  • Pulse — the group-level event ring triggers are modelled on
  • Animations — transition presets
  • Sync — receiving values and events

Generated from ControlDocs/symbol.md. Something unclear or missing? Tell me.