SFCompose brings SF Symbols to Android Jetpack Compose. Display static and animated symbols with configurable weights, optical scales, colors and replacement transitions.
SFCompose is available on Maven Central. Use the version shown in the Maven Central badge above; no repository credentials are required.
Add Maven Central to both plugin and dependency repositories in settings.gradle.kts:
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
}
}
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
}
}Add SFCompose to your version catalog, replacing <release-version> with the published version you want to use:
[versions]
sfcompose = "<release-version>"
[plugins]
sfcompose = { id = "io.github.nevodev.sfcompose", version.ref = "sfcompose" }Apply the plugin in your Android app's build.gradle.kts, alongside your Android and Compose plugins:
plugins {
alias(libs.plugins.sfcompose)
}The plugin adds io.github.nevodev:sfcompose-catalog and its runtime dependency automatically.
You do not need an additional implementation declaration. It packages the data selected by your symbol references.
Consumers of the published artifacts need neither Python nor the original system resources.
The project's Android SDK and dependency versions are listed in the version catalog.
For an existing explicit catalog dependency, set sfcompose { automaticDependency.set(false) } to avoid adding it again.
To use private symbols alongside the public catalog, add this to your app's build.gradle.kts
after applying the SFCompose plugin:
sfcompose {
additionalCatalogs.add("io.github.nevodev:sfcompose-catalog-private:${libs.versions.sfcompose.get()}")
}The plugin adds the private dependency and packages the referenced symbols automatically;
no separate implementation declaration is needed. Use PrivateSFSymbols for these entries:
import com.nevoit.sfcompose.symbols.PrivateSFSymbols
import com.nevoit.sfcompose.symbols.SFSymbol
// Inside a @Composable function:
SFSymbol(PrivateSFSymbols.Apps.Ipad.Badge.Icloud.Bold, contentDescription = "iPad apps in iCloud")If your app only needs the private catalog, use catalog.set(...) instead of additionalCatalogs.add(...):
sfcompose {
catalog.set("io.github.nevodev:sfcompose-catalog-private:${libs.versions.sfcompose.get()}")
}See the private catalog guide for more details.
Import the APIs from com.nevoit.sfcompose.symbols. The examples below belong inside a @Composable function.
Use IDE completion on SFSymbols to find names and variants:
import androidx.compose.ui.unit.dp
import com.nevoit.sfcompose.symbols.SFSymbol
import com.nevoit.sfcompose.symbols.SFSymbols
import com.nevoit.sfcompose.symbols.SymbolScale
SFSymbol(SFSymbols.Wifi, contentDescription = "Wi-Fi")
SFSymbol(
symbol = SFSymbols.Heart.Fill.Bold,
contentDescription = "Favorite",
pointSize = 24.dp,
scale = SymbolScale.Small,
)A bare entry uses Regular weight. Select a weight with .Bold, .Light and other named accessors;
use .Fill and other name variants where the catalog exposes them.
Set contentDescription = null for a decorative icon.
For a weight that changes at runtime, select .DynamicWeight and pass weight = currentWeight.
Fixed-weight entries package less data than dynamic-weight entries.
pointSizecontrols the requested slot height.scaleselects an optical design independently of that size.paddinginsets the drawing area within the slot, without increasing its requested size.displayModedefaults toSquareOverflow: a square slot that permits wide symbols to overflow. UseSquareFitWidthto fit wide symbols inside the square, orIntrinsicWidthfor the glyph's natural advance.
Pass a tint for a single icon, or provide LocalSFSymbolColor for a subtree.
The default tint is black; it does not automatically follow Material content colors.
CompositionLocalProvider(
LocalSFSymbolColor provides MaterialTheme.colorScheme.onSurface,
) {
SFSymbol(SFSymbols.Wifi, contentDescription = "Wi-Fi")
}Use Palette mode to assign colors to the symbol's source layers:
SFSymbol(
symbol = SFSymbols.Airtag.Radiowaves.Forward.Fill,
contentDescription = "AirTag",
mode = SymbolRenderingMode.Palette,
palette = listOf(Color.Blue, Color.Red),
gradients = true,
)Monochrome uses one tint, Hierarchical applies hierarchy opacity, and Multicolor uses the symbol's source colors.
Palette colors follow source palette levels rather than individual paths.
Use the .Animated entry with AnimatedSFSymbol and choose an effect:
AnimatedSFSymbol(
symbol = SFSymbols.Wifi.Animated,
contentDescription = "Wi-Fi",
animation = SymbolAnimation(effect = SymbolEffect.Bounce),
)For stroke drawing, use SymbolAnimation(drawEffect = SymbolDrawEffect.On) or Off on a symbol with Draw data.
The default empty SymbolAnimation() stays stationary.
To play on a tap, keep an animation state and turn off initial autoplay:
val animationState = rememberSymbolAnimationState()
AnimatedSFSymbol(
symbol = SFSymbols.Wifi.Animated,
contentDescription = "Wi-Fi",
modifier = Modifier.clickable { animationState.replay() },
state = animationState,
autoPlay = false,
animation = SymbolAnimation(effect = SymbolEffect.Bounce),
)Call replay() or change replayKey to restart playback. Hoist the state above a lazy item to pause
when the icon leaves composition and resume on reentry. Use a separate state for each icon.
startDelayMillis delays playback while holding its time-zero frame. To keep the full resting symbol visible
until a trigger, use autoPlay = false instead. For repeatable motion, set playback = SymbolEffectPlayback.Continuous;
repeatCount can limit its cycles. Draw On/Off is not repeated by that setting.
Pass the icon for the current UI state. The first icon appears after loading; subsequent changes animate automatically:
var selected by remember { mutableStateOf(false) }
SFSymbolReplace(
symbol = if (selected) SFSymbols.Person.Fill.Animated else SFSymbols.Person.Animated,
contentDescription = "Person",
modifier = Modifier.clickable { selected = !selected },
)Both entries must use .Animated. Changes during playback can reverse or interrupt the active replacement.
Use direction, preferMagic and layered to customize the transition.
- API guide and advanced loading
- Optional private-symbol catalog
- Building and publishing
- Renderer evidence and verification
Original SFCompose code is licensed under Apache-2.0. Imported Apple symbol resources are excluded from that license; see third-party notices.