Getting started

Use any of the over 5,000 icons provided by  Apple in your macOS application.

Please note: the package is only responsible to give you access to SF symbols on electron on macOS - the package does not handle different platforms and will likely produce errors on any other operating system than macOS.

⚠️ Legal ⚠️: SF Symbols are strictly copyrighted by Apple (read more here). This package is not intented to use the icons on any other platforms or in conflict with the guidelines provided by Apple Inc. This package generates the symbols on the fly, using rougly the same logic as the Electron.NativeImage.fromNamedImage API.

Installation

Install using your go-to package manager:

yarn add electron-sfsymbols

or

npm i -S electron-sfsymbols

Since the package uses a binary to generate the symbols, for it to work correctly the build options have to be updated.

# electron-builder.yaml

extraResources:
  - ./resources/**
  - from: node_modules/electron-sfsymbols/lib/bin/sfsymbol
    to: bin/sfsymbol

The package will look for the binary at resourcesPath/bin/sfsymbol - this path can be manually changed by passing a third argument to any of the methods.

Usage

Basic usage with Electron's NativeImage

Create a 24x24 pixel NativeImage from the specified SF Symbol

import { getSfSymbolAsNativeImage } from 'electron-sfsymbols';

// ...

const image = getSfSymbolAsNativeImage('folder', { mode: 'palette', weight: 'black' });

Usage with custom binary

Specify the path to the binary

import { getSfSymbolAsNativeImage } from 'electron-sfsymbols';

// ...

const image = getSfSymbolAsNativeImage(
  'folder',
  { mode: 'palette', weight: 'black' },
  join(getResourcesDirectory(), 'sfsymbol'),
);

Advance Usage

This package gives you access to all the basic options of SfSymbols:

| Parameter | Description | Type | Default | | :-------- | :------------------------------------------------------------------------------------------------------- | :-------------: | :----------: | | size | Size of the Symbol in pixels | Int | 24 | | scale | Scale of the Symbol, for retina displays. The resulting image will have the dimensions of size * scale | Int | 3 | | weight |  Weight of the Symbol |  SfSymbolWeight | regular | | mode |  Rendering mode of the symbol |  SfSymbolMode | monochrome | | variable | Controls the variable property of the symbol |  Float (0-1) |  1.0 | | primary |  Primary color of the symbol | SfSymbolColor | #0000000 | | secondary | Secondary color of the symbol | SfSymbolColor | #0000000 | | Tertiary | Tertiary color of the symbol | SfSymbolColor | #0000000 |

Colors

The symbols can accept either rgba colors, hex or css colors.

Please note: For unrecognised or malformed colors the package throws an UNRECOGNISED_COLOR error.

| Primary Color |  Secondary Color |  Tertiary Color |  Result | | :------------------------: | :--------------------------------: | :-------------: | :--------------------------------------: | | #EF2D56 | #ED7D3A33 | - | | | { r: 239, g: 45, b: 86 } | { r: 237, g: 125, b:58, a: 0.4 } | - | | | [239, 45, 86] | [237, 125, 58, 0.4] | - | | | red | orange | - | |

Modes

| Mode code |  Description |  Example | | :--------------- | :------------------------------------------------- | :-----------------------------------------------: | | monochrome | The default rendering mode for the symbols  | | | palette | Define a range of colors for the symbol  | | | hierarchical | Let the symbol decide the hierarchy of the colors  | | | multicolor | Use the multicolor version of the symbol | |

Configurations used for the examples:

Monochrome:

const options: SfSymbolOptions = {
  mode: 'monochrome',
  primary: '00000000',
};

Palette:

const options: SfSymbolOptions = {
  mode: 'palette',
  primary: 'FFFFFFFF',
  secondary: '00FF00FF',
  tertiary: '00FF00FF',
};

Hierarchical:

const options: SfSymbolOptions = {
  mode: 'multicolor',
  primary: '00000000',
};

Multicolor

const options: SfSymbolOptions = {
  mode: 'multicolor',
};

Variable Symbols

Many of the SF Symbols are variable icons - these symbols can be controlled using the variable option; a float between 0 and 1.

Examples:

| Variable |  Example  | | :------- | :-----------------------------------------------: | | 1.0 |   | | 0.5 |   | | 0.0 |   |

Weights

Sf Symbols support 8 weights other than the regular one

| Weight | Example | | :----------- | :--------------------------------------------: | | ultralight |   | | thin |   | | light |   | | regular |   | | medium |   | | semibold |   | | bold |   | | heavy |   | | black |   |

🤝 Contributing

Contributions, issues and feature requests are welcome!Feel free to check issues page.

Show your support

Give a ⭐️ if this project helped you!

Or buy me a coffee 🙌🏾

📝 License

Copyright © 2022 Balázs Szalay. This project is MIT licensed.