SF Symbol

Element type: Dictionary

The SFSymbol component allows you to display any valid SF Symbol inside your Octory view.
It supports customizable rendering modes, colors, weight, size, and variable symbol values.

Keys

Name	Type	Possible values	Required
Type	String	SFSymbol	Required
Name	String	-	Required
Rendering	String	Monochrome, Hierarchical, Palette, Multicolor
SFColor	Dictionary	-
VariableValue	Number	-
Size	Number	-
SystemFontWeight	String	Bold, Black, Heavy, Light, Medium, Regular, Semibold, Thin, UltraLight
Alignment	String	Left, Center, Right
Animation	Dictionary	-
Margins	Dictionary (Margins)	-
Condition PRO	Dictionary (Condition)	-

Detail

Type Required

Type: String
Explanation: Must be set to SFSymbol to declare this component.

Name Required

Type: String
Explanation: The identifier of the SF Symbol to display. This value must correspond to a valid SF Symbol name available on macOS.

Rendering

Type: String
Possible values: Monochrome, Hierarchical, Palette, Multicolor
Default: Monochrome
Explanation: Determines the symbol rendering style.

• Monochrome: Draws the symbol using a single color.
• Hierarchical: Applies hierarchical shading using a base color.
• Palette: Uses up to three user-defined colors from SFColor.
• Multicolor: Uses Apple’s predefined multicolor symbol if supported.

SFColor

Type: Dictionary
Explanation: Defines the color(s) applied to the symbol.

• When using Monochrome, Hierarchical, or Multicolor, only Color1 is applied.
• When using Palette, Color1, Color2, and Color3 are applied to build the palette.
  Each color entry follows the same format as the standard color object (LightMode, DarkMode, AlphaLight, AlphaDark).
  If omitted, the symbol inherits the default system text color.

VariableValue

Type: Number
Default: 1
Explanation: Controls the “completion” or fill level of variable SF Symbols. Supported symbols may represent partial states based on a value between 0 and 1. 1 means fully filled.

Size

Type: Number
Default: 20
Explanation: Sets the rendered size of the SF Symbol in points.

SystemFontWeight

Type: String
Possible values: Bold, Black, Heavy, Light, Medium, Regular, Semibold, Thin, UltraLight
Default: Regular
Explanation: Specifies the weight used when rendering the symbol, affecting its visual stroke thickness.

Alignment

Type: String
Possible values: Left, Center, Right
Default: Center
Availability: 3.1.0+
Explanation: Where the symbol sits horizontally within the width available to it.

Animation

Type: Dictionary
Availability: 3.1.0+
Explanation: Animates the symbol with one of the native SF Symbol effects. The dictionary holds the keys described below.

Name	Type	Possible values	Required
Effect	String	Bounce, Pulse, VariableColor, Wiggle, Rotate, Breathe, DrawOn, DrawOff	Required
Direction	String	Up, Down, Left, Right, Clockwise, CounterClockwise, Forward, Backward
Layers	String	WholeSymbol, ByLayer, Individually
Repeats	Number	-
Speed	Number	-
Delay	Number	-
Cumulative	Boolean	-
Reversing	Boolean	-
HideInactiveLayers	Boolean	-

Effect Required

Type: String
Possible values: Bounce, Pulse, VariableColor, Wiggle, Rotate, Breathe, DrawOn, DrawOff
Explanation: The animation played on the symbol.

Direction

Type: String
Possible values: Up, Down, Left, Right, Clockwise, CounterClockwise, Forward, Backward
Explanation: The direction of the effect. Only some effects accept a direction, and each accepts only some of the values, see the compatibility table below.

Layers

Type: String
Possible values: WholeSymbol, ByLayer, Individually
Explanation: Whether the effect is applied to the symbol as a whole, or layer by layer.

Repeats

Type: Number
Explanation: How many times the effect is played. Must be 1 or more. If not specified, the effect repeats indefinitely.

Speed

Type: Number
Default: 1
Explanation: A multiplier on the speed of the effect. Must be greater than 0: a value of 2 plays it twice as fast.

Delay

Type: Number
Explanation: A delay in seconds, 0 or more. If not specified, repetitions chain immediately. For DrawOn and DrawOff, which play once, it delays that single run.

Cumulative, Reversing and HideInactiveLayers

Type: Boolean
Explanation: Fine tune the VariableColor effect: whether layers stay lit as the effect progresses, whether it plays backwards once finished, and whether inactive layers are hidden instead of dimmed. These three keys are only accepted with Effect set to VariableColor.

warning

These keys are validated when the configuration is loaded, and an incompatible combination makes it fail. The accepted combinations are:

Effect	Direction	Repeats	Layers
Bounce	Up, Down	yes	WholeSymbol, ByLayer
Rotate	Clockwise, CounterClockwise	yes	WholeSymbol, ByLayer
Wiggle	all values	yes	WholeSymbol, ByLayer
Pulse, Breathe	not accepted	yes	WholeSymbol, ByLayer
VariableColor	not accepted	yes	not accepted
DrawOn, DrawOff	not accepted	not accepted	also accepts Individually

info

Animations follow the system accessibility settings. When the end user turns on Reduce Motion, the effects that move the symbol are suppressed, while Pulse and VariableColor keep playing since they only change opacity and color.

Margins

Type: Dictionary
Reference: Margins
Explanation: Adds margins around the symbol, following the margin configuration standards.

Condition PRO

Type: Dictionary
Reference: Condition
Explanation: Allows this component to appear conditionally when using Octory Pro.

Examples

The following displays an image using an online URL.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<!-- ... -->
	<key>Slides</key>
	<array>
		<dict>
			<key>Containers</key>
			<array>
				<dict>
					<key>Components</key>
					<array>
						<dict>
							<key>Type</key>
							<string>SFSymbol</string>
							<key>Name</key>
							<string>square.and.arrow.up</string>
							<key>Rendering</key>
							<string>Palette</string>
							<key>SFColor</key>
							<dict>
								<key>Color1</key>
								<dict>
									<key>DarkMode</key>
									<string>#E76F51</string>
									<key>LightMode</key>
									<string>#3FA7D6</string>
									<key>AlphaLight</key>
									<integer>1</integer>
									<key>AlphaDark</key>
									<integer>1</integer>
								</dict>
								<key>Color2</key>
								<dict>
									<key>AlphaLight</key>
									<integer>1</integer>
									<key>AlphaDark</key>
									<integer>1</integer>
									<key>DarkMode</key>
									<string>#6A4C93</string>
									<key>LightMode</key>
									<string>#F4A261</string>
								</dict>
							</dict>
							<key>Size</key>
							<integer>100</integer>
							<key>SystemFontWeight</key>
							<string>Regular</string>
						</dict>
					</array>
				</dict>
			</array>
		</dict>
	</array>
	<!-- ... -->
</dict>
</plist>

A spinning symbol, left aligned, used to show that something is in progress.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<!-- ... -->
	<key>Components</key>
	<array>
		<dict>
			<key>Type</key>
			<string>SFSymbol</string>
			<key>Name</key>
			<string>arrow.clockwise.circle.fill</string>
			<key>Size</key>
			<real>28</real>
			<key>Alignment</key>
			<string>Left</string>
			<key>Animation</key>
			<dict>
				<key>Effect</key>
				<string>Rotate</string>
				<key>Direction</key>
				<string>Clockwise</string>
				<key>Speed</key>
				<real>1.5</real>
			</dict>
		</dict>
	</array>
	<!-- ... -->
</dict>
</plist>