Skip to content
A simple, consistent interface for managing user preferences within an Electron application.
JavaScript CSS HTML
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets First Jan 3, 2018
example afterLoad Mar 5, 2019
misc Demo GIF Jan 3, 2018
scss First Jan 3, 2018
src/app 2.0.0 Sep 21, 2019
.gitignore Ignore build folder Apr 30, 2018
.npmignore v0.0.2 Jan 3, 2018
CODE_OF_CONDUCT.md No Code of Conduct Jan 3, 2018
Gruntfile.js Added support for 'help' text at the field level Jan 4, 2018
LICENSE
README.md typo Sep 20, 2019
index.js added to the BrowserWindow opts since electron now defaults this to f… Sep 9, 2019
package-lock.json typo Sep 20, 2019
package.json 2.0.0 Sep 21, 2019
webpack.config.js First Jan 3, 2018

README.md

Electron Preferences

Introduction

This package provides Electron developers with a simple, consistent interface for managing user preferences. It includes two primary components:

  • A GUI interface within which the users of your application can manage their preferences.
  • An API for interacting with the service.

Using the API, developers can:

  • Define default preferences
  • Read / write values on demand
  • Define the layout of the preferences window.

To see the library in action, clone this repository and see the demo application that is included within the example folder:

$ git clone https://github.com/tkambler/electron-preferences.git
$ cd electron-preferences
$ npm i
$ npm run build
$ npm run example

Getting Started

Initializing the Preferences Service

Within your application's main process, create a new instance of the ElectronPreferences class, as shown below.

const electron = require('electron');
const app = electron.app;
const path = require('path');
const os = require('os');
const ElectronPreferences = require('electron-preferences');

const preferences = new ElectronPreferences({
    /**
     * Where should preferences be saved?
     */
    'dataStore': path.resolve(app.getPath('userData'), 'preferences.json'),
    /**
     * Default values.
     */
    'defaults': {
        'notes': {
            'folder': path.resolve(os.homedir(), 'Notes')
        },
        'markdown': {
            'auto_format_links': true,
            'show_gutter': false
        },
        'preview': {
            'show': true
        },
        'drawer': {
            'show': true
        }
    },
    /**
     * If the `onLoad` method is specified, this function will be called immediately after
     * preferences are loaded for the first time. The return value of this method will be stored as the
     * preferences object.
     */
    'onLoad': (preferences) => {
        // ...
        return preferences;
    },
    /**
     * The preferences window is divided into sections. Each section has a label, an icon, and one or
     * more fields associated with it. Each section should also be given a unique ID.
     */
    'sections': [
        {
            'id': 'about',
            'label': 'About You',
            /**
             * See the list of available icons below.
             */
            'icon': 'single-01',
            'form': {
                'groups': [
                    {
                        /**
                         * Group heading is optional.
                         */
                        'label': 'About You',
                        'fields': [
                            {
                                'label': 'First Name',
                                'key': 'first_name',
                                'type': 'text',
                                /**
                                 * Optional text to be displayed beneath the field.
                                 */
                                'help': 'What is your first name?'
                            },
                            {
                                'label': 'Last Name',
                                'key': 'last_name',
                                'type': 'text',
                                'help': 'What is your last name?'
                            },
                            {
                                'label': 'Gender',
                                'key': 'gender',
                                'type': 'dropdown',
                                'options': [
                                    {'label': 'Male', 'value': 'male'},
                                    {'label': 'Female', 'value': 'female'},
                                    {'label': 'Unspecified', 'value': 'unspecified'},
                                ],
                                'help': 'What is your gender?'
                            },
                            {
                                'label': 'Which of the following foods do you like?',
                                'key': 'foods',
                                'type': 'checkbox',
                                'options': [
                                    { 'label': 'Ice Cream', 'value': 'ice_cream' },
                                    { 'label': 'Carrots', 'value': 'carrots' },
                                    { 'label': 'Cake', 'value': 'cake' },
                                    { 'label': 'Spinach', 'value': 'spinach' }
                                ],
                                'help': 'Select one or more foods that you like.'
                            },
                            {
                                'label': 'Coolness',
                                'key': 'coolness',
                                'type': 'slider',
                                'min': 0,
                                'max': 9001
                            },
                            {
                                'label': 'Eye Color',
                               'key': 'eye_color',
                                'type': 'color',
                                'format': 'hex', // can be hex, hsl or rgb
                                'help': 'Your eye color'
                            },
                            {
                                'label': 'Hair Color',
                                'key': 'hair_color',
                                'type': 'color',
                                'format': 'rgb',
                                'help': 'Your hair color'
                            }
                        ]
                    }
                ]
            }
        },
        {
            'id': 'notes',
            'label': 'Notes',
            'icon': 'folder-15',
            'form': {
                'groups': [
                    {
                        'label': 'Stuff',
                        'fields': [
                            {
                                'label': 'Read notes from folder',
                                'key': 'folder',
                                'type': 'directory',
                                'help': 'The location where your notes will be stored.'
                            },
                            {
                                'heading': 'Important Message',
                                'content': '<p>The quick brown fox jumps over the long white fence. The quick brown fox jumps over the long white fence. The quick brown fox jumps over the long white fence. The quick brown fox jumps over the long white fence.</p>',
                                'type': 'message',
                            }
                        ]
                    }
                ]
            }
        },
        {
            'id': 'space',
            'label': 'Other Settings',
            'icon': 'spaceship',
            'form': {
                'groups': [
                    {
                        'label': 'Other Settings',
                        'fields': [
                            {
                                'label': 'Phone Number',
                                'key': 'phone_number',
                                'type': 'text',
                                'help': 'What is your phone number?'
                            },
                            {
                                'label': "Foo or Bar?",
                                'key': 'foobar',
                                'type': 'radio',
                                'options': [
                                    {'label': 'Foo', 'value': 'foo'},
                                    {'label': 'Bar', 'value': 'bar'},
                                    {'label': 'FooBar', 'value': 'foobar'},
                                ],
                                'help': 'Foo? Bar?'
                            }
                        ]
                    }
                ]
            }
        }
    ]
});

Interacting with the Preferences Service from the Main Process

// Show the preferences window on demand.
preferences.show();

// Get a value from the preferences data store
const myPref = preferences.value('some.nested.key');

// Save a value within the preferences data store
preferences.value('some.nested.key', 'my-value');

// Subscribing to preference changes.
preferences.on('save', (preferences) => {
    console.log(`Preferences were saved.`, JSON.stringify(preferences, null, 4));
});

Interacting with the Preferences Service from the Renderer Process

const { ipcRenderer, remote } = require('electron');

// Fetch the preferences object
const preferences = ipcRenderer.sendSync('getPreferences');

// Display the preferences window
ipcRenderer.send('showPreferences');

// Listen to the `preferencesUpdated` event to be notified when preferences are changed.
ipcRenderer.on('preferencesUpdated', (e, preferences) => {
    console.log('Preferences were updated', preferences);
});

// Instruct the preferences service to update the preferences object from within the renderer.
ipcRenderer.sendSync('setPreferences', { ... });

Field Types

The library includes built-in support for the following field types:

  • Text
  • Dropdown
  • Message
  • Folder selection
  • Checkbox
  • Radio
  • Slider
  • Accelerator (for shortcut input)
  • Color picker

Adding support for additional field types if easy, if you're familiar with React. PR's for such additions are welcome.

Icons

The following icons come packaged with the library and can be specified when you define the layout of your preferences window.

Name Icon
archive-2
archive-paper
award-48
badge-13
bag-09
barcode-qr
bear-2
bell-53
bookmark-2
briefcase-24
calendar-60
camera-20
cart-simple
chat-46
check-circle-07
cloud-26
compass-05
dashboard-level
diamond
edit-78
email-84
eye-19
favourite-31
flag-points-32
flash-21
folder-15
gift-2
grid-45
handout
heart-2
home-52
image
key-25
layers-3
like-2
link-72
lock-open
lock
multiple-11
notes
pencil
phone-2
preferences
send-2
settings-gear-63
single-01
single-folded-content
skull-2
spaceship
square-download
square-upload
support-16
trash-simple
turtle
vector
video-66
wallet-43
widget
world
zoom-2
You can’t perform that action at this time.