Electron Documentation1.7.8

Docs / API / systemPreferences

systemPreferences

Get system preferences.

Process: Main

const {systemPreferences} = require('electron')
console.log(systemPreferences.isDarkMode())

Events

The systemPreferences object emits the following events:

Event: ‘accent-color-changed’ Windows

Returns:

Event: ‘color-changed’ Windows

Returns:

Event: ‘inverted-color-scheme-changed’ Windows

Returns:

Methods

systemPreferences.isDarkMode() macOS

Returns Boolean - Whether the system is in Dark Mode.

systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOS

Returns Boolean - Whether the Swipe between pages setting is on.

systemPreferences.postNotification(event, userInfo) macOS

Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.

systemPreferences.postLocalNotification(event, userInfo) macOS

Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.

systemPreferences.subscribeNotification(event, callback) macOS

Subscribes to native notifications of macOS, callback will be called with callback(event, userInfo) when the corresponding event happens. The userInfo is an Object that contains the user information dictionary sent along with the notification.

The id of the subscriber is returned, which can be used to unsubscribe the event.

Under the hood this API subscribes to NSDistributedNotificationCenter, example values of event are:

systemPreferences.unsubscribeNotification(id) macOS

Removes the subscriber with id.

systemPreferences.subscribeLocalNotification(event, callback) macOS

Same as subscribeNotification, but uses NSNotificationCenter for local defaults. This is necessary for events such as NSUserDefaultsDidChangeNotification

systemPreferences.unsubscribeLocalNotification(id) macOS

Same as unsubscribeNotification, but removes the subscriber from NSNotificationCenter.

systemPreferences.getUserDefault(key, type) macOS

Returns any - The value of key in system preferences.

This API uses NSUserDefaults on macOS. Some popular key and types are:

systemPreferences.setUserDefault(key, type, value) macOS

Set the value of key in system preferences.

Note that type should match actual type of value. An exception is thrown if they don’t.

This API uses NSUserDefaults on macOS. Some popular key and types are:

systemPreferences.isAeroGlassEnabled() Windows

Returns Boolean - true if DWM composition (Aero Glass) is enabled, and false otherwise.

An example of using it to determine if you should create a transparent window or not (transparent windows won’t work correctly when DWM composition is disabled):

const {BrowserWindow, systemPreferences} = require('electron')
let browserOptions = {width: 1000, height: 800}

// Make the window transparent only if the platform supports it.
if (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {
  browserOptions.transparent = true
  browserOptions.frame = false
}

// Create the window.
let win = new BrowserWindow(browserOptions)

// Navigate.
if (browserOptions.transparent) {
  win.loadURL(`file://${__dirname}/index.html`)
} else {
  // No transparency, so we load a fallback that uses basic styles.
  win.loadURL(`file://${__dirname}/fallback.html`)
}

systemPreferences.getAccentColor() Windows

Returns String - The users current system wide accent color preference in RGBA hexadecimal form.

const color = systemPreferences.getAccentColor() // `"aabbccdd"`
const red = color.substr(0, 2) // "aa"
const green = color.substr(2, 2) // "bb"
const blue = color.substr(4, 2) // "cc"
const alpha = color.substr(6, 2) // "dd"

systemPreferences.getColor(color) Windows

Returns String - The system color setting in RGB hexadecimal form (#ABCDEF). See the Windows docs for more details.

systemPreferences.isInvertedColorScheme() Windows

Returns Boolean - true if an inverted color scheme, such as a high contrast theme, is active, false otherwise.


See something that needs fixing? Propose a change on the source.
Need a different version of the docs? See the available versions or community translations.
Want to search all the documentation at once? See all of the docs on one page.