{"id":12014,"library":"sf-symbols-typescript","title":"SF Symbols for TypeScript","description":"sf-symbols-typescript is a utility library providing TypeScript type definitions for Apple's SF Symbols. It enables developers to use SF Symbol names as string literal types, enhancing type safety in applications that consume these icons, particularly useful in environments like React Native. The current stable version is 2.2.0. The library primarily updates its types in sync with new releases of SF Symbols from Apple, incorporating new icons and symbol versions. Its key differentiators include having zero runtime dependencies and zero runtime code, making it a pure type-level utility. It also offers advanced features for restricting the available symbols globally via declaration merging or individually by importing specific version types, which is crucial for maintaining compatibility with target iOS/macOS versions.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/nandorojo/typescript-sf-symbols","tags":["javascript","typescript"],"install":[{"cmd":"npm install sf-symbols-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add sf-symbols-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add sf-symbols-typescript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is a type-only import. Using `import` without `type` will result in an error as there's no runtime value.","wrong":"import { SFSymbol } from 'sf-symbols-typescript'","symbol":"SFSymbol","correct":"import type { SFSymbol } from 'sf-symbols-typescript'"},{"note":"To restrict symbols to a specific version, import the corresponding type like `SFSymbols5_0`. Ensure you use `import type`.","wrong":"import { SFSymbols5_0 } from 'sf-symbols-typescript'","symbol":"SFSymbols{major}_{minor}","correct":"import type { SFSymbols5_0 } from 'sf-symbols-typescript'"},{"note":"The `Overrides` interface is meant for declaration merging to globally restrict SF Symbol versions. Do not attempt to import it directly.","wrong":"import { Overrides } from 'sf-symbols-typescript'","symbol":"Overrides (declaration merging)","correct":"declare module 'sf-symbols-typescript' { interface Overrides { SFSymbolsVersion: '6.0' } }"}],"quickstart":{"code":"import type { SFSymbol } from 'sf-symbols-typescript';\n\n// Basic usage: type-checking SF Symbol names\nconst basicIcon: SFSymbol = 'arrow.up';\n// const invalidIcon: SFSymbol = 'non.existent.symbol'; // This would cause a TypeScript error\n\n// Globally restricting SF Symbol versions using declaration merging\ndeclare module 'sf-symbols-typescript' {\n  interface Overrides {\n    // Restrict symbols to those found in SF Symbols 5.0 (e.g., for iOS 17.0+)\n    SFSymbolsVersion: '5.0';\n  }\n}\n\n// After declaration merging, SFSymbol now only includes 5.0 symbols.\n// This ensures your app only uses symbols available on its minimum target OS.\nconst restrictedIcon: SFSymbol = 'faceid'; // 'faceid' is available in 5.0\n// const newerIcon: SFSymbol = 'globe.desk'; // If 'globe.desk' was introduced in 6.0, this would now be a type error\n\n// Alternatively, importing specific version types for granular control\nimport type { SFSymbols6_0 } from 'sf-symbols-typescript';\nconst specificVersionIcon: SFSymbols6_0 = 'globe.desk'; // Explicitly use a 6.0 symbol type\n\nconsole.log(`Using basic icon: ${basicIcon}`);\nconsole.log(`Using restricted icon: ${restrictedIcon}`);\nconsole.log(`Using specific version icon: ${specificVersionIcon}`);\n\n// This library has no runtime code, so these lines just demonstrate type usage.\n// In a real app, you would pass these strings to a native UI component.\n","lang":"typescript","description":"Demonstrates basic usage of `SFSymbol` for type safety, global restriction via declaration merging, and importing version-specific symbol types."},"warnings":[{"fix":"Migrate any custom version restriction logic to use the `declare module 'sf-symbols-typescript' { interface Overrides { SFSymbolsVersion: 'X.Y' } }` pattern, or import specific version types like `SFSymbolsX_Y`.","message":"Version 2 introduced a new mechanism for specifying SF Symbols compatibility through declaration merging with the `Overrides` interface. This replaces any previous, less flexible methods of version restriction.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always use `import type { SFSymbol } from 'sf-symbols-typescript'` for type-only imports to ensure it's stripped correctly during compilation.","message":"The package provides only TypeScript types. There is no JavaScript runtime code or default export. Attempting a standard `import SFSymbol from 'sf-symbols-typescript'` or `require('sf-symbols-typescript')` will result in runtime or build errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Move global `declare module 'sf-symbols-typescript' { ... }` blocks to a dedicated `.d.ts` file in your project's root or `src` directory, ensuring it's picked up by the TypeScript compiler.","message":"When restricting symbols globally via `Overrides` interface declaration merging, ensure the `declare module` block is in a global declaration file (e.g., `src/globals.d.ts` or `src/types.d.ts`) that is included in your `tsconfig.json`. Placing it directly in a `.ts` or `.tsx` file that's part of your main application logic might not apply it globally.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Remember that `SFSymbol` is a TypeScript type only. It has no runtime representation. It should only be used in type annotations or declarations, such as `const icon: SFSymbol = '...'`.","cause":"Attempting to use `SFSymbol` or other type imports as if they were runtime values (e.g., `console.log(SFSymbol)` or passing it to a functionExpectingAValue).","error":"Error: \"SFSymbol\" cannot be used as a value because it was imported using 'import type'."},{"fix":"Ensure you are using declaration merging correctly: `declare module 'sf-symbols-typescript' { interface Overrides { SFSymbolsVersion: 'X.Y' } }` in a global `.d.ts` file. Do not try to import or extend `Overrides` as a regular interface.","cause":"This error occurs if you're trying to directly modify the `Overrides` interface without using a `declare module` block, or if your `declare module` block for `Overrides` is syntactically incorrect.","error":"Property 'SFSymbolsVersion' does not exist on type 'Overrides'."},{"fix":"Double-check the symbol name for typos. If you've restricted the `SFSymbol` type to an older version (e.g., '5.0'), ensure the symbol you're using is available in that version. Consult the SF Symbols app or the Version Support Table in the package's README to verify symbol availability for your chosen version.","cause":"This error means the string literal you provided does not match any of the valid SF Symbol names defined by the `SFSymbol` type. This can happen if you made a typo, or if you restricted the `SFSymbol` type to an older version of SF Symbols and are trying to use a newer symbol.","error":"Type '\"non.existent.symbol\"' is not assignable to type 'SFSymbol'."}],"ecosystem":"npm"}