SF Symbols to SVG

SF Symbols to SVGs. Period.

Apple SF Symbols is an icon set with more than 7,000 symbols. Unfortunately, this are not available on the web. This tool solve this.

Warning

This tool requires you to have the SF Pro Text font installed on your system or in a custom directory.

Tip

SF Symbols to SVG can be coupled with React from SVG to generate React components from SVGs.

Usage

SF Symbols to SVG is available as a CLI tool:

npx sf-symbols-svg --help

Available Options

--size, -s       Font size for symbols (default: 24)
--padding, -p    Padding in pixels (default: 2)
--weight, -w     Font weights to include (default: regular)
                 Can specify multiple: -w regular -w bold
--output, -o     Output directory (default: ./sf-symbols-svgs)
--fonts-dir, -f  Directory containing SF Pro Text fonts (default: /Library/Fonts)
--sf-version     SF Symbols version to use (default: latest)
--sources-dir    Directory containing SF Symbols data files (default: ./sources)
--icons-list     Path to a file containing a list of icons to process, one name per line (optional)
--help, -h       Show this help message
--version        Show version of SF Symbols supported by this tool.

Note

SF Symbols to SVG will always try to use the latest version of SF Symbols supported by this tool. You can check in the sources/ directory to see which versions are supported.

Examples

# Generate SVGs for the latest version of SF Symbols, in 24x24 SVGs with 2px padding, in ./svg-symbols-svgs folder
npx sf-symbols-svg --weight all

# Generate SVGs with larger size and padding
sf-symbols-svg --size 32 --padding 4

# Generate SVGs for multiple weights
sf-symbols-svg --weight bold --weight black

# Specify custom output directory
sf-symbols-svg --output ./my-icons

# Specify a different SF Symbols version (if available)
sf-symbols-svg --sf-version 6.0

# Combine options
sf-symbols-svg --size 48 --padding 8 --weight light --weight regular --weight bold --output ./custom-icons --fonts-dir /Users/moox/Library/Fonts

# Process only specific icons
sf-symbols-svg --icons-list /path/to/your/icons-list.txt

Creating a new version

When Apple ships a new SF Symbols version, add it to this tool by creating a new folder in sources/. The tool detects versions from the folder names and uses the most recent one as the default (see SF Symbols Versions).

1. Create a new directory in sources/{version}/ (example: sources/8.0/). Use a plain numeric name (8.0, not 8.0-beta) so version sorting keeps working — the tool compares versions numerically.

2. Extract the character mappings from the SF Symbols app:

   • Get the SF Symbols app and open it
   • Switch to the list view (the list icon in the toolbar)
   • Select all symbols (cmd + A or Edit > Select All)
   • Press the right arrow key to expand every group, so all variants (.fill, .circle, .slash, numbered variants, …) are revealed and selected — see the note below
   • With everything selected, right click and press Copy {x} symbols as Text
   • Paste into a file at sources/{version}/symbols.txt
   • Right click again and press Copy {x} names
   • Paste into a file at sources/{version}/names.txt
   • Both files must have the same number of entries, aligned line by line (the tool pairs them by index). symbols.txt may be one glyph per line or a single continuous string — both are supported.

   [!IMPORTANT] Since SF Symbols 8, the app groups symbol variants under a single base symbol in the default grid view. A plain "Select All + Copy" there only copies the base of each group and silently drops thousands of variants. Use the list view and expand all groups with the right arrow key before copying so the full set is captured. After copying, sanity-check the counts: the number of lines in symbols.txt and names.txt must match, and should be close to the symbol count the app shows on launch (e.g. 7151 for the SF Symbols 8 beta).

3. Make sure you have the matching SF Pro font version installed (see Font Compatibility).

4. Test the new version locally before releasing:

   # Generate every symbol of the new (now default) version, all weights
   npm run dev
   
   # Or target a subset to iterate quickly
   node --experimental-strip-types ./src/index.ts --sf-version 8.0 --icons-list ./src/test-icons.txt --output ./test-output
   
   # Run the test suite
   npm run test

That's it! The tool will automatically detect the new version and use it as the default (since it's the most recent).

Releasing a beta version

When a new SF Symbols version is still in beta, Apple may add or rename symbols before the final release. Ship it as a prerelease so it does not become the default npm install for everyone:

1. Add the version folder as above (e.g. sources/8.0/) and fill in symbols.txt / names.txt from the beta SF Symbols app.

2. Set a prerelease version in package.json (e.g. 8.0.0-beta.123).

3. Publish under the beta dist-tag so it does not become the default latest:

   npx npmpub --tag beta

Users opt into the beta explicitly:

npm install sf-symbols-svg@beta
# or
npx sf-symbols-svg@beta --weight all

Important

Once the SF Symbols version is final, re-extract the data from the stable app (the beta is often missing or renames symbols), set the version to the stable x.y.z, and release it normally with npm run release so the stable version becomes the default (latest).

About SF Symbols Versions and Font Compatibility

SF Symbols Versions

This tool automatically detects supported SF Symbols versions by scanning the sources/ directory. Each version requires its own data files (symbols.txt and names.txt) which are already included in the repository for some versions.

The tool will automatically use the most recent version as the default, but you can specify a different version using the --sf-version option. If no matching versions are detected in the sources/ directory, the tool will display an error message.

To add support for a new SF Symbols version, see Creating a new version.

Using a Custom Sources Directory

If you want to use a different directory for your SF Symbols data files, you can specify it with the --sources-dir option:

sf-symbols-svg --sources-dir /path/to/your/sources

The custom sources directory must follow the same structure as the default one:

sources/
  ├── 6.0/
  │   ├── symbols.txt
  │   └── names.txt
  ├── 6.1/
  │   ├── symbols.txt
  │   └── names.txt
  └── ...

The tool will automatically detect available versions from the provided directory and use the most recent one as the default.

Processing Only Specific Icons

If you want to process only a limited subset of icons, you can create a text file with one icon name per line and use the --icons-list option:

sf-symbols-svg --icons-list /path/to/your/icons-list.txt

Example of an icons list file:

moon.stars.fill
puzzlepiece
amplifier
figure.hiking

This is particularly useful for:

• Testing the tool with a smaller set of icons
• Generating only the specific icons you need for your project
• Reducing processing time when you only need a few symbols

Font Compatibility

Warning

SF Symbols requires specific SF Pro Text font versions that match the SF Symbols version you're using. If the font versions don't match, the symbols may not render correctly.

Caution

The Apple SF Symbols app will display a warning at the top of the application if your installed fonts don't match the expected version. Make sure to check this warning and install the appropriate font version from Apple's website.

About Font Files

To use this script, you need to have the SF Pro Text fonts installed on your system or in a custom directory.

Using system-installed fonts (recommended)

If you have SF Pro Text fonts installed on your system (typically in /Library/Fonts), the script will automatically find and use them. This is the default behavior.

# Use fonts from the default location (/Library/Fonts)
sf-symbols-svg

Using fonts from a custom directory

If your fonts are installed in a different location, you can specify it with the --fonts-dir option:

# Use fonts from a custom location
sf-symbols-svg --fonts-dir ~/Library/Fonts

Installing SF Pro Text fonts

If you don't have the fonts installed:

1. Download SF Pro font from Apple's website.
2. Install the font using the provided installer.
3. The fonts will be installed in /Library/Fonts by default.

---

Note

For legal reasons, this repository does not include the SF Pro Text font files. You must download and install them from Apple's website. Make sure to use font versions that are compatible with the SF Symbols version you are using (check for warnings in the SF Symbols app).