SF Symbols for TypeScript

Common errors

• Error: "SFSymbol" cannot be used as a value because it was imported using 'import type'.

  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).
  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 = '...'`.

• Property 'SFSymbolsVersion' does not exist on type 'Overrides'.

  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.
  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.

• Type '"non.existent.symbol"' is not assignable to type 'SFSymbol'.

  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.
  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.

Warnings

• breaking 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.
  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`.
• gotcha 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.
  Fix: Always use `import type { SFSymbol } from 'sf-symbols-typescript'` for type-only imports to ensure it's stripped correctly during compilation.
• gotcha 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.
  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.

Install

• npm install sf-symbols-typescript npm
• yarn add sf-symbols-typescript yarn
• pnpm add sf-symbols-typescript pnpm

Imports

• SFSymbol
  wrong:

  import { SFSymbol } from 'sf-symbols-typescript'

  correct:

  import type { SFSymbol } from 'sf-symbols-typescript'

  This is a type-only import. Using `import` without `type` will result in an error as there's no runtime value.
• SFSymbols{major}_{minor}
  wrong:

  import { SFSymbols5_0 } from 'sf-symbols-typescript'

  correct:

  import type { SFSymbols5_0 } from 'sf-symbols-typescript'

  To restrict symbols to a specific version, import the corresponding type like `SFSymbols5_0`. Ensure you use `import type`.
• Overrides (declaration merging)
  wrong:

  import { Overrides } from 'sf-symbols-typescript'

  correct:

  declare module 'sf-symbols-typescript' { interface Overrides { SFSymbolsVersion: '6.0' } }

  The `Overrides` interface is meant for declaration merging to globally restrict SF Symbol versions. Do not attempt to import it directly.

Quickstart

Demonstrates basic usage of `SFSymbol` for type safety, global restriction via declaration merging, and importing version-specific symbol types.

import type { SFSymbol } from 'sf-symbols-typescript';

// Basic usage: type-checking SF Symbol names
const basicIcon: SFSymbol = 'arrow.up';
// const invalidIcon: SFSymbol = 'non.existent.symbol'; // This would cause a TypeScript error

// Globally restricting SF Symbol versions using declaration merging
declare module 'sf-symbols-typescript' {
  interface Overrides {
    // Restrict symbols to those found in SF Symbols 5.0 (e.g., for iOS 17.0+)
    SFSymbolsVersion: '5.0';
  }
}

// After declaration merging, SFSymbol now only includes 5.0 symbols.
// This ensures your app only uses symbols available on its minimum target OS.
const restrictedIcon: SFSymbol = 'faceid'; // 'faceid' is available in 5.0
// const newerIcon: SFSymbol = 'globe.desk'; // If 'globe.desk' was introduced in 6.0, this would now be a type error

// Alternatively, importing specific version types for granular control
import type { SFSymbols6_0 } from 'sf-symbols-typescript';
const specificVersionIcon: SFSymbols6_0 = 'globe.desk'; // Explicitly use a 6.0 symbol type

console.log(`Using basic icon: ${basicIcon}`);
console.log(`Using restricted icon: ${restrictedIcon}`);
console.log(`Using specific version icon: ${specificVersionIcon}`);

// This library has no runtime code, so these lines just demonstrate type usage.
// In a real app, you would pass these strings to a native UI component.