{"id":1537,"url":"https://github.com/SFSafeSymbols/SFSafeSymbols","last_synced_at":"2025-08-02T04:31:36.790Z","repository":{"id":37023526,"uuid":"190158042","full_name":"SFSafeSymbols/SFSafeSymbols","owner":"SFSafeSymbols","description":"Safely access Apple's SF Symbols using static typing","archived":false,"fork":false,"pushed_at":"2024-07-21T21:06:39.000Z","size":1930,"stargazers_count":1708,"open_issues_count":10,"forks_count":63,"subscribers_count":22,"default_branch":"stable","last_synced_at":"2024-10-29T15:11:05.404Z","etag":null,"topics":["icons","ios","sfsymbols","swift","symbols"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SFSafeSymbols.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-04T08:10:42.000Z","updated_at":"2024-10-26T00:11:50.000Z","dependencies_parsed_at":"2023-02-16T17:45:38.440Z","dependency_job_id":"a426a406-e50b-4754-84a5-a174b3bcc68c","html_url":"https://github.com/SFSafeSymbols/SFSafeSymbols","commit_stats":{"total_commits":264,"total_committers":22,"mean_commits":12.0,"dds":"0.46212121212121215","last_synced_commit":"ba8ff2b89729be225d5b9fd5802447f2809fae64"},"previous_names":["piknotech/sfsafesymbols"],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SFSafeSymbols%2FSFSafeSymbols","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SFSafeSymbols%2FSFSafeSymbols/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SFSafeSymbols%2FSFSafeSymbols/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SFSafeSymbols%2FSFSafeSymbols/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SFSafeSymbols","download_url":"https://codeload.github.com/SFSafeSymbols/SFSafeSymbols/tar.gz/refs/heads/stable","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227956036,"owners_count":17846987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["icons","ios","sfsymbols","swift","symbols"],"created_at":"2024-01-05T20:15:49.226Z","updated_at":"2025-08-02T04:31:36.774Z","avatar_url":"https://github.com/SFSafeSymbols.png","language":"Swift","funding_links":[],"categories":["Media","Swift"],"sub_categories":["Image"],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/SFSafeSymbols/SFSafeSymbols/stable/Logo.png\" width=600\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"https://app.bitrise.io/app/f9e56287b4a18852#/builds\"\u003e\n\t\t\u003cimg src=\"https://app.bitrise.io/app/f9e56287b4a18852/status.svg?token=PwV0AjHnLm32ht_GGzff3w\u0026branch=stable\" alt=\"Build Status\"\u003e\n\t\u003c/a\u003e\n    \u003ca href=\"#\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/swift-6-FFAC45.svg\" alt=\"Swift: 6\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/SFSafeSymbols/SFSafeSymbols/releases\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/version-6.2-blue.svg\"\n    alt=\"Version: 6.2\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"#\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Platforms-iOS%20|%20tvOS%20|%20watchOS%20|%20macOS-FF69B4.svg\"\n        alt=\"Platforms: iOS – tvOS – watchOS – macOS\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/SFSafeSymbols/SFSafeSymbols/blob/stable/LICENSE\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/license-MIT-lightgrey.svg\" alt=\"License: MIT\"\u003e\n    \u003c/a\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/apple/swift-package-manager\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/SwiftPM-compatible-brightgreen.svg\" alt=\"SwiftPM: Compatible\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/Carthage/Carthage\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat\" alt=\"Carthage: Compatible\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://cocoapods.org/pods/SFSafeSymbols\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/CocoaPods-compatible-4BC51D.svg?style=flat\" alt=\"CocoaPods: Compatible\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"#idea--features\"\u003eIdea \u0026 Features\u003c/a\u003e\n  • \u003ca href=\"#supported-versions\"\u003eSupported Versions\u003c/a\u003e\n  • \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\n  • \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\n  • \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\n  • \u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\n  • \u003ca href=\"https://github.com/SFSafeSymbols/SFSafeSymbols/issues\"\u003eIssues\u003c/a\u003e\n  • \u003ca href=\"https://github.com/SFSafeSymbols/SFSafeSymbols/pulls\"\u003ePull Requests\u003c/a\u003e\n\u003c/p\u003e\n\n## Idea \u0026 Features\n\nAt WWDC 2019, Apple announced a new library of icons that came included with that year's new operating system versions. To browse them, there's a [dedicated Mac app](https://developer.apple.com/design/human-interface-guidelines/sf-symbols/overview/) called SF Symbols. However, developers still have to copy the name of a symbol and reference it unsafely, resulting in code like this:\n\n```swift\nUIImage(systemName: \"circle.fill\")\n```\n\nIt didn't take long until [first ideas came up](https://twitter.com/simjp/status/1135642837322588161?s=12) to make these icons **accessible in a safe way** using a framework. And this is just the basic idea behind `SFSafeSymbols`!\n\nFurthermore, with `SFSafeSymbols`...\n\n- ... you can be sure your symbol code won't crash due to typos or symbol availability issues. This is because **all symbols are tested via a CI** (on the latest iOS \u0026 tvOS versions and also some earlier OS versions).\n- ... lookups in the SF Symbols app (e. g. about available **layersets**, available **localizations** \u0026 the **look of the symbol**) are no longer needed because every symbol is **documented in code**.\n- ... **multiple SF Symbols versions** are supported at the same time (via utilization of the `@availability` flag). Each symbol is only made available on those platform versions where Apple says it's available.\n- ... **renamed symbols can be detected easily** (via a deprecation notice which suggests the use of the new name at the same time).\n\n## Supported Versions\n\nThe following SF Symbols versions are currently supported:\n\n| SF Symbols Version | iOS Version | macOS Version | tvOS Version | watchOS Version |\n| ------------------ | ----------- | ------------- | ------------ | --------------- |\n| 1.0 | 13.0 | 11.0 | 13.0 | 6.0 |\n| 1.1 | 13.1 | 11.0 | 13.0 | 6.1 |\n| 2.0 | 14.0 | 11.0 | 14.0 | 7.0 |\n| 2.1 | 14.2 | 11.0 | 14.2 | 7.1 |\n| 2.2 | 14.5 | 11.3 | 14.5 | 7.4 |\n| 3.0 | 15.0 | 12.0 | 15.0 | 8.0 |\n| 3.1 | 15.1 | 12.0 | 15.1 | 8.1 |\n| 3.2 | 15.2 | 12.1 | 15.2 | 8.3 |\n| 3.3 | 15.4 | 12.3 | 15.4 | 8.5 |\n| 4.0 | 16.0 | 13.0 | 16.0 | 9.0 |\n| 4.1 | 16.1 | 13.0 | 16.1 | 9.1 |\n| 4.2 | 16.4 | 13.3 | 16.4 | 9.4 |\n| 5.0 | 17.0 | 14.0 | 17.0 | 10.0 |\n| 5.1 | 17.1 | 14.1 | 17.1 | 10.1 |\n| 5.2 | 17.2 | 14.2 | 17.2 | 10.2 |\n| 5.3 | 17.4 | 14.4 | 17.4 | 10.4 |\n| 5.4 | 17.6 | 14.6 | 17.6 | 10.6 |\n| 6.0 | 18.0 | 15.0 | 18.0 | 11.0 |\n| 6.1 | 18.1 | 15.1 | 18.1 | 11.1 |\n| 6.2 | 18.2 | 15.2 | 18.2 | 11.2 |\n\n## Installation\n\n`SFSafeSymbols` can be installed via the **Swift Package Manager (recommended)**, Carthage or CocoaPods.\n\nSupported platforms are `iOS (11.0+)`, `macOS (10.13+)`, `tvOS (11.0+)` and `watchOS (4.0+)`, although the actual functionality is of course only accessible starting with `iOS 13.0`, `macOS 11.0`, `tvOS 13.0` and `watchOS 6.0`.\n\n### Swift Package Manager (Xcode-integrated)\n\nTo integrate SFSafeSymbols using the Xcode-built-in SPM, choose `File` → `Swift Packages` → `Add Package Dependency`. Enter the following url: `https://github.com/SFSafeSymbols/SFSafeSymbols` and click `Next`. When asked about the version, leave the preselection and click `Next`. In the following step, select `SFSafeSymbols` as the package product and click `Finish`.\n\n### Swift Package Manager (standalone)\n\nTo integrate using the standalone version of Apple's Swift Package Manager, add the following as a dependency to your `Package.swift`:\n\n```swift\n.package(url: \"https://github.com/SFSafeSymbols/SFSafeSymbols.git\", .upToNextMajor(from: \"6.2\"))\n```\n\nAfter specifying `\"SFSafeSymbols\"` as a dependency of the target in which you want to use it, run `swift package update`.\n\n### Carthage\n\nAdd the following entry to your Cartfile:\n\n```\ngithub \"SFSafeSymbols/SFSafeSymbols\" ~\u003e 6.2\n```\n\nThen run `carthage update`.\n\n### CocoaPods\n\nAdd the following entry to your Podfile:\n\n```rb\npod 'SFSafeSymbols', '~\u003e 6.2'\n```\n\nThen run `pod install`.\n\n## Usage\n\nAll the system symbols are accessible via the `SFSymbol` type. They are named similar to Apple's names, but use a lower camel case style and prefix names with leading numbers with a `_` character:\n\n```\nc.circle        ~\u003e SFSymbol.cCircle\ne.circle.fill   ~\u003e SFSymbol.eCircleFill\n11.circle.fill  ~\u003e SFSymbol._11CircleFill\n```\n\nA SF Symbol `UIImage` can now be initialized using the `SFSymbol` type. This image is already unwrapped, so you get a `UIImage` instead of a `UIImage?`:\n\n```swift\nUIImage(systemSymbol: .cCircle)\nUIImage(systemSymbol: SFSymbol.eCircleFill)\nUIImage(systemSymbol: ._11CircleFill, withConfiguration: /* Some UIImage.Configuration */)\n```\n\nA SF Symbol `SwiftUI.Image` can also be initialized using the `SFSymbol` type:\n\n```swift\nImage(systemSymbol: .cCircle)\nImage(systemSymbol: SFSymbol.eCircleFill)\n```\n\nThere are also `SwiftUI.Label` initializers:\n\n```swift\nLabel(\"MyText\", systemSymbol: .cCircle)\nLabel(LocalizedStringKey(\"my.text\"), systemSymbol: SFSymbol.eCircleFill)\n```\n\n... and an initializer for `SwiftUI.Button`:\n\n```swift\nButton(\"MyText\", systemSymbol: .cCircle){}\nButton(LocalizedStringKey(\"my.text\"), systemSymbol: SFSymbol.eCircleFill){}\nButton(\"MyText\", systemSymbol: .cCircle, role: .cancel){}\nButton(LocalizedStringKey(\"my.text\"), systemSymbol: SFSymbol.eCircleFill, role: .cancel){}\nButton(\"MyText\", systemSymbol: .cCircle, role: .cancel, intent: intent)\nButton(LocalizedStringKey(\"my.text\"), systemSymbol: SFSymbol.eCircleFill, intent: intent)\n```\n\n... and an initializer for `UIApplicationShortcutItem`:\n\n```swift\nUIApplicationShortcutIcon(systemSymbol: .cCircle)\nUIApplicationShortcutIcon(systemSymbol: SFSymbol.eCircleFill)\n```\n\n... and finally also an initializer for AppKit's `NSImage`:\n\n```swift\nNSImage(systemSymbol: .cCircle)\nNSImage(systemSymbol: SFSymbol.eCircleFill, accessibilityDescription: \"some.description\")\n```\n\n### Localization\n\nSF Symbols can come with multiple different localizations. `SFSafeSymbols` exposes localization the following way:\n\n- Implicit localization: When using an `SFSymbol`, it gets automatically localized to the user's current locale - nothing to do on your part. This behavior is managed by Apple's system implementation of SF Symbols.\n\n- Explicit localization: `SFSafeSymbols` lets you access a symbol's localized versions as follows:\n\n  ```swift\n  // 1. Static localization:\n  let a = SFSymbol.character.ar // corresponds to \"character.ar\"\n  let b = SFSymbol.character.zh // corresponds to \"character.zh\"\n  let c = SFSymbol.character.rtl // doesn't compile: \"character.rtl\" doesn't exist\n  // a, b have type SFSymbol\n  \n  // 2. Dynamic localization:\n  SFSymbol.character.availableLocalizations // [.ar, .he, .hi, .ja, .ko, .th, .zh, .zhTraditional]\n  let a = SFSymbol.character.localized(to: .ar)\n  let b = SFSymbol.character.localized(to: .rtl)\n  // a, b have type SFSymbol?\n  ```\n\n  Static localization only exposes the localizations which are actually available, so you cannot accidentally localize a non-localizable symbol.\n\n  Dynamic localization, in contrast, is useful when dealing with an array of `SFSymbol`s which all have different available localizations.\n\nAttention: Serializing and deserializing `SFSymbol`s currently makes them lose their _explicit_ static localization information. Dynamic localization information will still be retained.\n\n### Swiftlint\n\nYou may want to leverage [SwiftLint](https://github.com/realm/SwiftLint) to ensure that `SFSafeSymbols` is used when appropriate. In your `.swiftlint.yml` file, you can add a custom rule like this:\n```yml\ncustom_rules:\n  sf_safe_symbol:\n    name: \"Safe SFSymbol\"\n    message: \"Use `SFSafeSymbols` via `systemSymbol` parameters for type safety.\"\n    regex: \"(Image\\\\(systemName:)|(NSImage\\\\(symbolName:)|(Label[^,]+?,\\\\s*systemImage:)|(UIApplicationShortcutIcon\\\\(systemImageName:)\"\n    severity: warning\n```\n\n## Contributing\n\nContributions are very much welcome! See [CONTRIBUTING.md](https://github.com/SFSafeSymbols/SFSafeSymbols/blob/stable/CONTRIBUTING.md) for more information.\n\n## License\n\nThis library is released under the [MIT License](http://opensource.org/licenses/MIT). See [LICENSE](https://github.com/SFSafeSymbols/SFSafeSymbols/blob/stable/LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSFSafeSymbols%2FSFSafeSymbols","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSFSafeSymbols%2FSFSafeSymbols","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSFSafeSymbols%2FSFSafeSymbols/lists"}