2016-04-25 06:36:38 +00:00
# systemPreferences
> Get system preferences.
2016-11-23 19:20:56 +00:00
Process: [Main ](../glossary.md#main-process )
2016-11-03 17:26:00 +00:00
2016-06-19 15:53:34 +00:00
```javascript
2018-09-13 16:10:51 +00:00
const { systemPreferences } = require('electron')
2016-07-26 01:39:25 +00:00
console.log(systemPreferences.isDarkMode())
2016-06-19 15:53:34 +00:00
```
2016-09-16 16:08:41 +00:00
## Events
The `systemPreferences` object emits the following events:
### Event: 'accent-color-changed' _Windows_
Returns:
* `event` Event
2016-12-22 03:21:04 +00:00
* `newColor` String - The new RGBA color the user assigned to be their system
2016-10-07 16:55:50 +00:00
accent color.
2016-09-16 16:08:41 +00:00
2016-10-11 16:35:14 +00:00
### Event: 'color-changed' _Windows_
Returns:
* `event` Event
2016-10-07 16:55:50 +00:00
### Event: 'inverted-color-scheme-changed' _Windows_
Returns:
* `event` Event
2018-10-31 14:22:18 +00:00
* `invertedColorScheme` Boolean - `true` if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is being used, `false` otherwise.
### Event: 'high-contrast-color-scheme-changed' _Windows_
Returns:
* `event` Event
* `highContrastColorScheme` Boolean - `true` if a high contrast theme is being used, `false` otherwise.
2016-09-16 16:08:41 +00:00
2018-09-27 15:33:31 +00:00
### Event: 'appearance-changed' _macOS_
Returns:
* `newAppearance` String - Can be `dark` or `light`
**NOTE:** This event is only emitted after you have called `startAppLevelAppearanceTrackingOS`
2016-04-25 06:36:38 +00:00
## Methods
2016-06-18 13:26:26 +00:00
### `systemPreferences.isDarkMode()` _macOS_
2016-04-25 06:36:38 +00:00
2016-10-06 10:03:37 +00:00
Returns `Boolean` - Whether the system is in Dark Mode.
2016-04-25 06:36:38 +00:00
2016-08-03 02:27:56 +00:00
### `systemPreferences.isSwipeTrackingFromScrollEventsEnabled()` _macOS_
2016-09-24 23:59:30 +00:00
Returns `Boolean` - Whether the Swipe between pages setting is on.
2016-08-03 02:27:56 +00:00
2016-08-05 21:02:59 +00:00
### `systemPreferences.postNotification(event, userInfo)` _macOS_
* `event` String
2016-09-20 21:26:55 +00:00
* `userInfo` Object
2016-08-05 21:02:59 +00:00
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
2016-09-20 21:26:55 +00:00
* `userInfo` Object
2016-08-05 21:02:59 +00:00
Posts `event` as native notifications of macOS. The `userInfo` is an Object
that contains the user information dictionary sent along with the notification.
2018-03-22 09:41:03 +00:00
### `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.
2016-06-18 13:26:26 +00:00
### `systemPreferences.subscribeNotification(event, callback)` _macOS_
2016-04-25 06:36:38 +00:00
* `event` String
* `callback` Function
2016-10-13 06:30:57 +00:00
* `event` String
* `userInfo` Object
2016-04-25 06:36:38 +00:00
2016-06-18 13:26:26 +00:00
Subscribes to native notifications of macOS, `callback` will be called with
2016-05-18 05:40:19 +00:00
`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` .
2016-04-25 06:36:38 +00:00
Under the hood this API subscribes to `NSDistributedNotificationCenter` ,
2016-05-18 05:40:19 +00:00
example values of `event` are:
2016-04-25 06:36:38 +00:00
* `AppleInterfaceThemeChangedNotification`
* `AppleAquaColorVariantChanged`
* `AppleColorPreferencesChangedNotification`
* `AppleShowScrollBarsSettingChanged`
2016-06-21 00:48:42 +00:00
### `systemPreferences.subscribeLocalNotification(event, callback)` _macOS_
2016-08-25 17:52:19 +00:00
* `event` String
* `callback` Function
2016-10-13 06:30:57 +00:00
* `event` String
* `userInfo` Object
2016-08-25 17:52:19 +00:00
2016-06-21 00:48:42 +00:00
Same as `subscribeNotification` , but uses `NSNotificationCenter` for local defaults.
2017-11-29 10:38:35 +00:00
This is necessary for events such as `NSUserDefaultsDidChangeNotification` .
2016-06-21 00:48:42 +00:00
2018-03-22 09:41:03 +00:00
### `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` .
2016-06-21 00:48:42 +00:00
### `systemPreferences.unsubscribeLocalNotification(id)` _macOS_
2016-08-25 17:52:19 +00:00
* `id` Integer
2016-06-21 00:48:42 +00:00
Same as `unsubscribeNotification` , but removes the subscriber from `NSNotificationCenter` .
2018-03-22 09:41:03 +00:00
### `systemPreferences.unsubscribeWorkspaceNotification(id)` _macOS_
* `id` Integer
Same as `unsubscribeNotification` , but removes the subscriber from `NSWorkspace.sharedWorkspace.notificationCenter` .
2017-12-12 18:08:09 +00:00
### `systemPreferences.registerDefaults(defaults)` _macOS_
2017-12-13 21:02:15 +00:00
* `defaults` Object - a dictionary of (`key: value`) user defaults
2017-12-12 18:08:09 +00:00
Add the specified defaults to your application's `NSUserDefaults` .
2016-06-18 13:26:26 +00:00
### `systemPreferences.getUserDefault(key, type)` _macOS_
2016-04-25 06:36:38 +00:00
* `key` String
* `type` String - Can be `string` , `boolean` , `integer` , `float` , `double` ,
2017-11-29 10:38:35 +00:00
`url` , `array` or `dictionary` .
2016-04-25 06:36:38 +00:00
2017-10-10 19:55:15 +00:00
Returns `any` - The value of `key` in `NSUserDefaults` .
2016-04-25 06:36:38 +00:00
2017-10-10 19:55:15 +00:00
Some popular `key` and `type` s are:
2016-11-28 23:08:22 +00:00
2017-11-29 10:58:24 +00:00
* `AppleInterfaceStyle` : `string`
* `AppleAquaColorVariant` : `integer`
* `AppleHighlightColor` : `string`
* `AppleShowScrollBars` : `string`
* `NSNavRecentPlaces` : `array`
* `NSPreferredWebServices` : `dictionary`
* `NSUserDictionaryReplacementItems` : `array`
2016-11-28 23:08:22 +00:00
### `systemPreferences.setUserDefault(key, type, value)` _macOS_
* `key` String
2018-03-13 23:07:36 +00:00
* `type` String - See [`getUserDefault` ](#systempreferencesgetuserdefaultkey-type-macos ).
2016-11-28 23:08:22 +00:00
* `value` String
2017-10-10 19:55:15 +00:00
Set the value of `key` in `NSUserDefaults` .
2016-11-28 23:08:22 +00:00
Note that `type` should match actual type of `value` . An exception is thrown
if they don't.
2017-10-10 19:55:15 +00:00
Some popular `key` and `type` s are:
2016-11-28 23:08:22 +00:00
2017-11-29 10:58:24 +00:00
* `ApplePressAndHoldEnabled` : `boolean`
2016-04-25 06:36:38 +00:00
2017-10-10 19:55:15 +00:00
### `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` .
2016-04-25 06:36:38 +00:00
### `systemPreferences.isAeroGlassEnabled()` _Windows_
2017-05-31 17:34:14 +00:00
Returns `Boolean` - `true` if [DWM composition][dwm-composition] (Aero Glass) is
2016-04-25 06:36:38 +00:00
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):
```javascript
2018-09-13 16:10:51 +00:00
const { BrowserWindow, systemPreferences } = require('electron')
let browserOptions = { width: 1000, height: 800 }
2016-04-25 06:36:38 +00:00
// Make the window transparent only if the platform supports it.
2016-04-30 15:50:04 +00:00
if (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {
2016-07-26 01:39:25 +00:00
browserOptions.transparent = true
browserOptions.frame = false
2016-04-25 06:36:38 +00:00
}
// Create the window.
2016-07-26 01:39:25 +00:00
let win = new BrowserWindow(browserOptions)
2016-04-25 06:36:38 +00:00
// Navigate.
if (browserOptions.transparent) {
2016-07-26 01:39:25 +00:00
win.loadURL(`file://${__dirname}/index.html`)
2016-04-25 06:36:38 +00:00
} else {
// No transparency, so we load a fallback that uses basic styles.
2016-07-26 01:39:25 +00:00
win.loadURL(`file://${__dirname}/fallback.html`)
2016-04-25 06:36:38 +00:00
}
```
[dwm-composition]:https://msdn.microsoft.com/en-us/library/windows/desktop/aa969540.aspx
2016-09-16 16:08:41 +00:00
2016-09-24 18:45:34 +00:00
### `systemPreferences.getAccentColor()` _Windows_
2016-09-16 16:08:41 +00:00
2016-10-11 16:32:03 +00:00
Returns `String` - The users current system wide accent color preference in RGBA
hexadecimal form.
2016-09-16 16:08:41 +00:00
```js
2016-09-24 18:45:34 +00:00
const color = systemPreferences.getAccentColor() // `"aabbccdd"`
2016-09-16 16:08:41 +00:00
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"
```
2016-10-06 22:31:43 +00:00
2016-10-11 16:32:03 +00:00
### `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][windows-colors] for more details.
2018-10-31 14:22:18 +00:00
[windows-colors]:https://msdn.microsoft.com/en-us/library/windows/desktop/ms724371(v=vs.85).aspx
2016-10-06 22:31:43 +00:00
### `systemPreferences.isInvertedColorScheme()` _Windows_
2018-10-31 14:22:18 +00:00
Returns `Boolean` - `true` if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is active, `false` otherwise.
2016-10-11 16:32:03 +00:00
2018-10-31 14:22:18 +00:00
### `systemPreferences.isHighContrastColorScheme()` _Windows_
Returns `Boolean` - `true` if a high contrast theme is active, `false` otherwise.
2018-09-27 15:33:31 +00:00
### `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 ](https://developer.apple.com/documentation/appkit/nsapplication/2967171-effectiveappearance?language=objc )
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
2018-10-02 04:44:50 +00:00
the interim in order for your application to inherit the OS preference you must set the
`NSRequiresAquaSystemAppearance` key in your apps `Info.plist` to `false` . If you are
using `electron-packager` or `electron-forge` just set the `enableDarwinDarkMode`
packager option to `true` . See the [Electron Packager API ](https://github.com/electron-userland/electron-packager/blob/master/docs/api.md#darwindarkmodesupport )
for more details.
2018-09-27 15:33:31 +00:00
### `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 ](https://developer.apple.com/documentation/appkit/nsapplication/2967170-appearance?language=objc ).
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` .