Symbol Style#

These modifiers allow you to customize how SF Symbols are displayed and animated inside views, particularly with the Image component.

#symbolRenderingMode

Sets the rendering mode for symbol images within the view.

#Type

symbolRenderingMode?: SymbolRenderingMode

#Options (SymbolRenderingMode)

• "monochrome" – A single-color version using the foreground style
• "hierarchical" – Multiple layers with different opacities for depth (good for semantic coloring)
• "multicolor" – Uses the symbol's built-in colors
• "palette" – Allows layered tinting (like using multiple foregroundStyle layers)

#Example

<Image
  systemName="star.fill"
  symbolRenderingMode="palette"
  foregroundStyle={{
    primary: "red",
    secondary: "orange",
    tertiary: "yellow"
  }}
/>

#Explanation:

• symbolRenderingMode="palette" tells the system to render the symbol in multiple layered styles.
• foregroundStyle now uses an object with primary, secondary, and optionally tertiary layers to color those symbol layers individually.

This matches SwiftUI's behavior with .symbolRenderingMode(.palette) and .foregroundStyle(primary, secondary, tertiary).

#symbolVariant

Displays the symbol with a particular visual variant.

#Type

symbolVariant?: SymbolVariants

#Options (SymbolVariants)

• "none" – Default symbol with no variant
• "circle" – Encapsulated in a circle
• "square" – Encapsulated in a square
• "rectangle" – Encapsulated in a rectangle
• "fill" – Filled symbol
• "slash" – Adds a slash over the symbol (often used to indicate "off" states)

#Example

<Image
  systemName="wifi"
  symbolVariant="slash"
/>

#symbolEffect

Applies a symbol animation effect to the view. This can include transitions (appear/disappear), scale, bounce, rotation, breathing, pulsing, and wiggle effects. You can also bind the effect to a value so it animates when the value changes.

#Type

symbolEffect?: SymbolEffect

There are two forms of usage:

#1. Simple effects (transition, scale, etc.)

You can directly assign a symbol effect name:

#Examples

<Image
  systemName="heart"
  symbolEffect="appear"
/>

<Image
  systemName="checkmark"
  symbolEffect="scaleByLayer"
/>

#2. Value-bound discrete effects

These effects animate when the associated value changes.

#Type

symbolEffect?: {
  effect: DiscreteSymbolEffect
  value: string | number | boolean
}

#Example

<Image
  systemName="star.fill"
  symbolEffect={{
    effect: "bounce",
    value: isFavorited
  }}
/>

In this example, each time isFavorited changes, the bounce animation is triggered.

#Available Discrete Effects (DiscreteSymbolEffect)

These effects can be bound to values:

#Full Example

<Image
  systemName="bell.fill"
  symbolRenderingMode="hierarchical"
  symbolVariant="circle"
  symbolEffect={{
    effect: "breathePulse",
    value: isNotified
  }}
  foregroundStyle="indigo"
/>

This image uses:

• a hierarchical rendering mode
• a circular variant around the symbol
• a pulsing animation bound to isNotified state

#Summary