electron/docs/api/system-preferences.md

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 Event
• newColor String - The new RGBA color the user assigned to be their system accent color.

Event: 'color-changed' Windows

Returns:

• event Event

Event: 'inverted-color-scheme-changed' Windows

Returns:

• event Event
• invertedColorScheme Boolean - true if an inverted color scheme, such as a high contrast theme, is being used, false otherwise.

Event: 'appearance-changed' macOS

Returns:

• newAppearance String - Can be dark or light

NOTE: This event is only emitted after you have called startAppLevelAppearanceTrackingOS

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

• event String
• userInfo Object

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

• event String
• userInfo Object

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

systemPreferences.postWorkspaceNotification(event, userInfo) macOS

• event String
• userInfo Object

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

• event String
• callback Function
  • event String
  • userInfo Object

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:

• AppleInterfaceThemeChangedNotification
• AppleAquaColorVariantChanged
• AppleColorPreferencesChangedNotification
• AppleShowScrollBarsSettingChanged

systemPreferences.subscribeLocalNotification(event, callback) macOS

• event String
• callback Function
  • event String
  • userInfo Object

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

systemPreferences.subscribeWorkspaceNotification(event, callback) macOS

• event String
• callback Function
  • event String
  • userInfo Object

Same as subscribeNotification, but uses NSWorkspace.sharedWorkspace.notificationCenter. This is necessary for events such as NSWorkspaceDidActivateApplicationNotification.

systemPreferences.unsubscribeNotification(id) macOS

• id Integer

Removes the subscriber with id.

systemPreferences.unsubscribeLocalNotification(id) macOS

• id Integer

Same as unsubscribeNotification, but removes the subscriber from NSNotificationCenter.

systemPreferences.unsubscribeWorkspaceNotification(id) macOS

• id Integer

Same as unsubscribeNotification, but removes the subscriber from NSWorkspace.sharedWorkspace.notificationCenter.

systemPreferences.registerDefaults(defaults) macOS

• defaults Object - a dictionary of (key: value) user defaults

Add the specified defaults to your application's NSUserDefaults.

systemPreferences.getUserDefault(key, type) macOS

• key String
• type String - Can be string, boolean, integer, float, double, url, array or dictionary.

Returns any - The value of key in NSUserDefaults.

Some popular key and types are:

• AppleInterfaceStyle: string
• AppleAquaColorVariant: integer
• AppleHighlightColor: string
• AppleShowScrollBars: string
• NSNavRecentPlaces: array
• NSPreferredWebServices: dictionary
• NSUserDictionaryReplacementItems: array

systemPreferences.setUserDefault(key, type, value) macOS

• key String
• type String - See getUserDefault.
• value String

Set the value of key in NSUserDefaults.

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

Some popular key and types are:

• ApplePressAndHoldEnabled: boolean

systemPreferences.removeUserDefault(key) macOS

• key String

Removes the key in NSUserDefaults. This can be used to restore the default or global value of a key previously set with setUserDefault.

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

• color String - One of the following values:
  • 3d-dark-shadow - Dark shadow for three-dimensional display elements.
  • 3d-face - Face color for three-dimensional display elements and for dialog box backgrounds.
  • 3d-highlight - Highlight color for three-dimensional display elements.
  • 3d-light - Light color for three-dimensional display elements.
  • 3d-shadow - Shadow color for three-dimensional display elements.
  • active-border - Active window border.
  • active-caption - Active window title bar. Specifies the left side color in the color gradient of an active window's title bar if the gradient effect is enabled.
  • active-caption-gradient - Right side color in the color gradient of an active window's title bar.
  • app-workspace - Background color of multiple document interface (MDI) applications.
  • button-text - Text on push buttons.
  • caption-text - Text in caption, size box, and scroll bar arrow box.
  • desktop - Desktop background color.
  • disabled-text - Grayed (disabled) text.
  • highlight - Item(s) selected in a control.
  • highlight-text - Text of item(s) selected in a control.
  • hotlight - Color for a hyperlink or hot-tracked item.
  • inactive-border - Inactive window border.
  • inactive-caption - Inactive window caption. Specifies the left side color in the color gradient of an inactive window's title bar if the gradient effect is enabled.
  • inactive-caption-gradient - Right side color in the color gradient of an inactive window's title bar.
  • inactive-caption-text - Color of text in an inactive caption.
  • info-background - Background color for tooltip controls.
  • info-text - Text color for tooltip controls.
  • menu - Menu background.
  • menu-highlight - The color used to highlight menu items when the menu appears as a flat menu.
  • menubar - The background color for the menu bar when menus appear as flat menus.
  • menu-text - Text in menus.
  • scrollbar - Scroll bar gray area.
  • window - Window background.
  • window-frame - Window frame.
  • window-text - Text in 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.

systemPreferences.getEffectiveAppearance() macOS

Returns String - Can be dark, light or unknown.

Gets the macOS appearance setting that is currently applied to your application, maps to NSApplication.effectiveAppearance

Please note that until Electron is built targeting the 10.14 SDK, your application's effectiveAppearance will default to 'light' and won't inherit the OS preference. In the interim we have provided a helper method startAppLevelAppearanceTrackingOS() which emulates this behavior.

systemPreferences.getAppLevelAppearance() macOS

Returns String | null - Can be dark, light or unknown.

Gets the macOS appearance setting that you have declared you want for your application, maps to NSApplication.appearance. You can use the setAppLevelAppearance API to set this value.

systemPreferences.setAppLevelAppearance(appearance) macOS

• appearance String | null - Can be dark or light

Sets the appearance setting for your application, this should override the system default and override the value of getEffectiveAppearance.

systemPreferences.startAppLevelAppearanceTrackingOS() macOS

This is a helper method to make your application's "appearance" setting track the user's OS level appearance setting. I.e. your app will have dark mode enabled if the user's system has dark mode enabled.

You can track this automatic change with the appearance-changed event.

Note: This method is exempt from our standard deprecation cycle and will be removed without deprecation in an upcoming major release of Electron as soon as we target the 10.14 SDK

systemPreferences.stopAppLevelAppearanceTrackingOS() macOS

This is a helper method to stop your application tracking the OS level appearance setting. It is a no-op if you have not called startAppLevelAppearanceTrackingOS()

Note: This method is exempt from our standard deprecation cycle and will be removed without deprecation in an upcoming major release of Electron as soon as we target the 10.14 SDK