electron-sfsymbols

📦 electron-sfsymbols

Use SF Symbols in electron applications

Report Bug Request Feature

Electron SF Symbols✨

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.