feat(expo-image): Add SF Symbol support for Apple platforms#41907
Merged
feat(expo-image): Add SF Symbol support for Apple platforms#41907
Conversation
Introduces SFSymbolLoader for loading SF Symbols via 'sf:' URI scheme in iOS. Updates ImageModule to register the new loader, adds detection logic in ImageSource, and extends resolveSources utility to handle SF Symbol strings.
Added 'expo-image' to dependencies and updated the static rendering index page to display an image using expo-image. Also updated .env and README.md with minor improvements for local development and Apple Team ID setup.
Introduces support for SF Symbol transition effects (iOS 17+) in expo-image, including new effect types such as 'sf:bounce', 'sf:pulse', 'sf:variable-color', 'sf:scale', 'sf:appear', 'sf:disappear', and 'sf:replace'. Updates the iOS implementation to handle symbol animation start/stop, tracks SF Symbol sources, and documents the new effects in Image.types.ts. Also updates the static rendering E2E test page to demonstrate symbol transitions.
Introduces direct SF Symbol rendering in ImageView.swift, bypassing SDWebImage to preserve symbol properties and support symbol-specific transitions and effects. Updates the static rendering E2E test to use 'sf:faceid' and comments out 'autoplay' and 'tintColor' for demonstration. Also adds logic for handling the 'sf:replace' effect and symbol weight parsing, and updates related type definitions.
Introduces a `repeat` property to the ImageTransition type and iOS implementation, allowing SF Symbol animation effects to repeat a specified number of times or indefinitely. Updates example usage and TypeScript types to document and support the new option.
Expanded the ImageTransition types and iOS implementation to support additional SF Symbol transition effects introduced in iOS 17 and iOS 18, such as bounce, pulse, scale, appear, disappear, wiggle, rotate, breathe, and draw-on, including their directional and layer-specific variants. Updated documentation and example usage to reflect the new effects.
Simplifies SF Symbol effect enums by removing scoped variants and introduces a separate 'scope' property for layer animation control. Updates iOS implementation to support new scope logic and adds support for 'sf:draw/on' and 'sf:draw/off' effects (iOS 26+). Adjusts TypeScript types and documentation to reflect these changes and updates example usage in static rendering test page.
Updated ImageProps to support SF Symbols via the `sf:` prefix and added the `sf-symbols-typescript` dependency. Adjusted example usage in the static rendering app to demonstrate new SF Symbol options and transition effects.
Introduces support for additional SF Symbol replace transitions: 'sf:replace/down-up', 'sf:replace/up-up', and 'sf:replace/off-up'. Updates iOS implementation to handle these effects and improves type definitions and documentation for transition options.
Introduces a new `sfEffect` prop for SF Symbol animations, supporting strings, objects, and arrays for more flexible configuration. Removes SF Symbol animation options from the `transition` prop and updates iOS implementation to handle multiple effects. Updates TypeScript types and documentation to reflect the new API.
Introduces a new ImageSFSymbolScreen showcasing SF Symbol effects (iOS 17+ and iOS 18+) using expo-image, including various animation and style options. Updates navigation to include the new screen for iOS, adds related environment variables, and a prebuild script for template usage.
Adjusts the Image component to default the contentFit prop to 'contain' instead of 'cover' for SF Symbol sources, preserving their aspect ratio. Updates resolveContentFit utility and passes an isSFSymbol flag to ensure correct behavior.
Introduces a new `symbolWeight` prop for SF Symbol images in expo-image on iOS, allowing font weight to be set directly rather than via URL query parameters. Updates the Image component and native iOS implementation to use this prop, and removes related query parameter handling. Also updates the changelog and example usages to reflect support for `source="sf:star"`.
Updated SF Symbol transition effect names from 'sf:replace/down-up', 'sf:replace/up-up', and 'sf:replace/off-up' to 'sf:down-up', 'sf:up-up', and 'sf:off-up' respectively across TypeScript types, iOS implementation, and example usage. This change improves naming consistency and clarity for SF Symbol transitions.
Updated the resolveSfEffect function in Image.tsx to use multi-line parameter formatting for improved readability. No functional changes were made.
Co-authored-by: Expo Bot <34669131+expo-bot@users.noreply.github.com>
Collaborator
|
The Pull Request introduced fingerprint changes against the base commit: e889247 Fingerprint diff[
{
"op": "changed",
"beforeSource": {
"type": "dir",
"filePath": "../../packages/expo-image/ios",
"reasons": [
"expoAutolinkingIos"
],
"hash": "a692ef6fbf6e8966ce701c78a6f31bfec4d7222f"
},
"afterSource": {
"type": "dir",
"filePath": "../../packages/expo-image/ios",
"reasons": [
"expoAutolinkingIos"
],
"hash": "38e6c2ca1fd4462789170a7dc2dfe3079974973e"
}
}
]Generated by PR labeler 🤖 |
Introduces the imageStyle prop to ImageBackgroundProps, allowing custom styles to be applied directly to the background image. This provides more flexibility for styling the image separately from the container.
Contributor
|
Subscribed to pull request
Generated by CodeMention |
Co-authored-by: Aman Mittal <amandeepmittal@live.com>
tsapeta
approved these changes
Jan 12, 2026
Ubax
reviewed
Jan 13, 2026
Deleted EXPO_NO_GIT_STATUS from the .env file as it is no longer needed. Refactored SFSymbolLoader.swift to use shorthand optional binding for the url parameter.
Updated Image.tsx to use more precise ImageStyle & TextStyle typings when flattening styles. Also improved handling of fontWeightStyle for SFSymbols by ensuring it is always a string when passed as symbolWeight.
EvanBacon
added a commit
that referenced
this pull request
Jan 21, 2026
# Why - Follow up on #41907 - Add fontSize and color props to expo-image when using SF symbols to match the style options of SwiftUI which would pair with Tailwind to create a clean API: `<Image source="sf:star" className="text-lg text-sf-yellow" />` -> Large SF star in adaptive Apple yellow color. # Test Plan - Added to NCL, built to ensure it runs. --------- Co-authored-by: Expo Bot <34669131+expo-bot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
sourceprop extends our existing source system where we support URI strings such ashttps://and local resourcesfile://along with cross-app resourcesph://. Here we treat the SF symbols as a custom URI since they are local resources toosf:star— where the protocol issfand the pathname is the icon name as-is. This is typed strictly while still allowing arbitrary strings by using the typesf:${SFSymbolNames}. This particular system should be capable of scaling to any other android equivalent (though we already just pass strings in as-is for resources).<Image.SF />but that opinion can be added later.transitionprop and all the animations to the newsfEffectprop.In the future if we add
fontSizeandcolorstyle props then a Tailwind user could do the following:In my opinion, this API feels on par with SwiftUI in terms of ergonomics (minus the manual import for
expo-image).Test Plan
Simulator.Screen.Recording.-.iPhone.17.Pro.Max.-.2026-01-02.at.15.14.25.mov
Checklist
changelog.mdentry and rebuilt the package sources according to this short guidenpx expo prebuild& EAS Build (eg: updated a module plugin).