# webext-options-sync [](https://www.npmjs.com/package/webext-options-sync)
> Helps you manage and autosave your extension's options.
Main features:
- Define your default options
- Add autoload and autosave to your options `
```
```js
// Your options.js file
/* global optionsStorage */
optionsStorage.syncForm(document.querySelector('form'));
```
### Form autosave and autoload
When using the `syncForm` method, `OptionsSync` will serialize the form using [dom-form-serializer](https://github.com/jefersondaniel/dom-form-serializer), which uses the `name` attribute as `key` for your options. Refer to its readme for more info on the structure of the data.
Any user changes to the form are automatically saved into `chrome.storage.sync` after 300ms (debounced). It listens to `input` events.
#### Input validation
If your form fields have any [validation attributes](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation#Validation-related_attributes) they will not be saved until they become valid.
Since autosave and validation is silent, you should inform the user of invalid fields, possibly via CSS by using the `:invalid` selector:
```css
/* Style the element */
input:invalid {
color: red;
border: 1px solid red;
}
/* Or display a custom error message */
input:invalid ~ .error-message {
display: block;
}
```
## API
#### const optionsStorage = new OptionsSync(setup?)
Returns an instance linked to the chosen storage. It will also run any migrations if it's called in the background.
##### setup
Type: `object`
Optional. It should follow this format:
```js
{
defaults: { // recommended
color: 'blue'
},
migrations: [ // optional
savedOptions => {
if(savedOptions.oldStuff) {
delete savedOptions.oldStuff
}
}
],
}
```
###### defaults
Type: `object`
A map of default options as strings or booleans. The keys will have to match the options form fields' `name` attributes.
###### migrations
Type: `array`
A list of functions to run in the `background` when the extension is updated. Example:
```js
{
migrations: [
(options, defaults) => {
// Change the `options`
if(options.oldStuff) {
delete options.oldStuff
}
// No return needed
},
// Integrated utility that drops any properties that don't appear in the defaults
OptionsSync.migrations.removeUnused
],
}
```
> [!NOTE]
> The `options` argument will always include the `defaults` as well as any options that were saved before the update.
###### storageName
Type: `string`
Default: `'options'`
The key used to store data in `chrome.storage.sync`
###### logging
Type: `boolean`
Default: `true`
Whether info and warnings (on sync, updating form, etc.) should be logged to the console or not.
###### storageType
Type: `'local' | 'sync'`
Default: `sync`
What storage area type to use (sync storage vs local storage). Sync storage is used by default.
**Considerations for selecting which option to use:**
- Sync is default as it's likely more convenient for users.
- Firefox requires [`browser_specific_settings.gecko.id`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings) for the `sync` storage to work locally.
- Sync storage is subject to much tighter [quota limitations](https://developer.chrome.com/docs/extensions/reference/storage/#property-sync), and may cause privacy concerns if the data being stored is confidential.
#### optionsStorage.set(options)
This will merge the existing options with the object provided.
**Note:** Any values specified in `default` are not saved into the storage, to save space, but they will still appear when using `getAll`. You just have to make sure to always specify the same `defaults` object in every context (this happens automatically in the [Advanced usage](#advanced-usage) above.)
##### options
Type: `object`
Default: `{}`
Example: `{color: red}`
A map of default options as strings, booleans, numbers and anything accepted by [dom-form-serializer](https://github.com/jefersondaniel/dom-form-serializer)’s `deserialize` function.
#### optionsStorage.setAll(options)
This will override **all** the options stored with your `options`.
#### optionsStorage.getAll()
This returns a Promise that will resolve with all the options.
#### optionsStorage.onChanged(callback, signal?)
Listens to changes in the storage and calls the callback when the options are changed. The callback is called with the new and old options.
##### callback
Type: `(newOptions: object, oldOptions: object) => void`
##### signal
Type: `AbortSignal`
If provided, the callback will be removed when the signal is aborted.
#### optionsStorage.syncForm(form)
Any defaults or saved options will be loaded into the `