An Electron store with built-in preferences management
This package provides Electron developers with a simple, consistent interface for managing user preferences. It includes two primary components:
- A simple key/value store API for interacting with the service.
- A GUI interface allowing users to manage preference values in the frontend of your application.
- A drop-in Electron key/value store
- Built-in preference manager
- Icons for preference groups
- Default values
- Hidden values
- Color Picker and Accelerator input for keyboard shortcuts
- Easily read / write values via the built-in API
- Components are written in React, adding new inputs is straightforward
- Uses write-json-file under the hood
- Customize styles using CSS
- Customize the layout of the preference manager using JSON
The library includes built-in support for the following field types:
Preference type |
Description |
---|---|
text |
<input type="text"/> |
number |
<input type="number"/> |
dropdown |
<select> |
radio |
<input type="radio"/> |
checkbox |
<input type="checkbox"/> |
slider |
<input type="range"/> |
file |
<input type="file"/> |
accelerator |
Keyboard shortcut input |
color |
Color picker input using simonwep/pickr |
list |
Ordered list with create/read/update/delete functionality |
message |
Read-only HTML panel for displaying information |
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 install
$ npm run build
$ npm run example
$ npm run lint
To quickly add electron-preferences
to your existing Electron app:
# From your Electron project root...
$ npm install electron-preferences
Then import and initialize the preference store.
Within your application's main process, create a new instance of the ElectronPreferences
class, as shown below.
For an example usage of the library, check out example/preferences.js
const ElectronPreferences = require('electron-preferences');
// import ElectronPreferences from 'electron-preferences'; // ...or if you prefer to use module imports
const preferences = new ElectronPreferences({
// Override default preference BrowserWindow values
browserWindowOpts: { /* ... */ },
// Create an optional menu bar
menu: Menu.buildFromTemplate(/* ... */),
// Provide a custom CSS file, relative to your appPath.
css: 'preference-styles.css'
// Preference file path
dataStore: '~/preferences.json', // defaults to <userData>/preferences.json
// Preference default values
defaults: {
about: {
name: 'Albert'
}
},
// Preference sections visible to the UI
sections: [
{
id: 'about',
label: 'About You',
icon: 'single-01', // See the list of available icons below
form: {
groups: [
{
'label': 'About You', // optional
'fields': [
{
label: 'Name',
key: 'name',
type: 'text',
help': 'What is your name?'
},
// ...
]
},
// ...
]
}
},
// ...
]
})
// Show the preferences window on demand.
preferences.show();
// Get a value from the preferences data store
const name = preferences.value('about.name');
// Save a value within the preferences data store
preferences.value('about.name', 'Einstein');
// Subscribing to preference changes.
preferences.on('save', (preferences) => {
console.log(`Preferences were saved.`, JSON.stringify(preferences, null, 4));
});
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', { ... });
You prefer a dark theme over a light theme? No problem, we have them both. The library will use whatever theme you're using with Electron. See the example on how to add the option to your preferences.
Still not matching your layout? You can easily customize the complete look by injecting your own custom CSS!
The following icons come packaged with the library and can be specified when you define the layout of your preferences window.
const electron = require('electron');
const app = electron.app;
const path = require('path');
const os = require('os');
const ElectronPreferences = require('electron-preferences');
// import ElectronPreferences from 'electron-preferences' //Or if you prefer to use module imports
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
}
},
/**
* 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'
}
]
}
]
}
},
{
'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.',
'multiSelections': false,
'noResolveAliases': false,
'treatPackageAsDirectory': false,
'dontAddToRecent': true
},
{
'label': 'Select some images',
'key': 'images',
'type': 'file',
'help': 'List of selected images',
'filters': [
{ name: 'Joint Photographic Experts Group (JPG)', extensions: ['jpg', 'jpeg', 'jpe', 'jfif', 'jfi', 'jif'] },
{ name: 'Portable Network Graphics (PNG)', extensions: ['png'] },
{ name: 'Graphics Interchange Format (GIF)', extensions: ['gif'] },
{ name: 'All Images', extensions: ['jpg', 'jpeg', 'jpe', 'jfif', 'jfi', 'jif', 'png', 'gif'] },
//{ name: 'All Files', extensions: ['*'] }
],
'multiSelections': true, //Allow multiple paths to be selected
'showHiddenFiles': true, //Show hidden files in dialog
'noResolveAliases': false, //(macos) Disable the automatic alias (symlink) path resolution. Selected aliases will now return the alias path instead of their target path.
'treatPackageAsDirectory': false, //(macos) Treat packages, such as .app folders, as a directory instead of a file.
'dontAddToRecent': true //(windows) Do not add the item being opened to the recent documents list.
},
{
'label': 'Other Settings',
'fields': [
{
'label': "Foo or Bar?",
'key': 'foobar',
'type': 'radio',
'options': [
{'label': 'Foo', 'value': 'foo'},
{'label': 'Bar', 'value': 'bar'},
{'label': 'FooBar', 'value': 'foobar'},
],
'help': 'Foo? Bar?'
}
]
},
{
'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': 'lists',
'label': 'Lists',
'icon': 'notes',
'form': {
'groups': [
{
'label': 'Lists',
'fields': [
{
'label': 'Favorite foods',
'key': 'foods',
'type': 'list',
'size': 15,
'help': 'A list of your favorite foods',
'addItemValidator': /^[A-Za-z ]+$/.toString(),
'addItemLabel': 'Add favorite food'
},
{
'label': 'Best places to visit',
'key': 'places',
'type': 'list',
'size': 10,
'style': {
'width': '75%'
},
'help': 'An ordered list of nice places to visit',
'orderable': true
}
]
}
]
}
},
{
'id': 'space',
'label': 'Other Settings',
'icon': 'spaceship',
'form': {
'groups': [
{
'label': 'Other Settings',
'fields': [
{
'label': "Foo or Bar?",
'key': 'foobar',
'type': 'radio',
'options': [
{'label': 'Foo', 'value': 'foo'},
{'label': 'Bar', 'value': 'bar'},
{'label': 'FooBar', 'value': 'foobar'},
],
'help': 'Foo? Bar?'
}
]
}
]
}
}
],
/**
* These parameters on the preference window settings can be overwritten
*/
browserWindowOpts: {
'title': 'My custom preferences title',
'width': 900,
'maxWidth': 1000,
'height': 700,
'maxHeight': 1000,
'resizable': true,
'maximizable': false,
//...
},
/**
* These parameters create an optional menu bar
*/
menu: Menu.buildFromTemplate(
[
{
label: 'Window',
role: 'window',
submenu: [
{
label: 'Close',
accelerator: 'CmdOrCtrl+W',
role: 'close'
}
]
}
]
),
/**
* If you want to apply your own CSS. The path should be relative to your appPath.
*/
css: 'custom-style.css'
});