Preferences

Utilities for storing WordPress preferences.

Installation

Install the module

npm install @wordpress/preferences --save

This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

Examples

Data store

Preferences are persisted values of any kind.

Set the default preferences for any features on initialization by dispatching an action:

import { dispatch } from '@wordpress/data';
import { store as preferencesStore } from '@wordpress/preferences';

function initialize() {
    // ...

    dispatch( preferencesStore ).setDefaults(
        'namespace/editor-or-plugin-name',
        {
            myBooleanFeature: true,
        }
    );

    // ...
}

Or the get selector to get a preference value, and the set action to update a preference to any value:

wp.data
    .select( 'core/preferences' )
    .get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // 1
wp.data
    .dispatch( 'core/preferences' )
    .set( 'namespace/editor-or-plugin-name', 'myPreferenceName', 2 );
wp.data
    .select( 'core/preferences' )
    .get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // 2

Use the toggle action to flip a boolean preference between true and false:

wp.data
    .select( 'core/preferences' )
    .get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // true
wp.data
    .dispatch( 'core/preferences' )
    .toggle( 'namespace/editor-or-plugin-name', 'myPreferenceName' );
wp.data
    .select( 'core/preferences' )
    .get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // false

Components

The PreferenceToggleMenuItem components can be used with a DropdownMenu to implement a menu for changing preferences.

Also see the MoreMenuDropdown component from the @wordpress/interface package for implementing a more menu.

function MyEditorMenu() {
    return (
        <MoreMenuDropdown>
            { () => (
                <MenuGroup label={ __( 'Features' ) }>
                    <PreferenceToggleMenuItem
                        scope="namespace/editor-or-plugin-name"
                        name="myPreferenceName"
                        label={ __( 'My feature' ) }
                        info={ __( 'A really awesome feature' ) }
                        messageActivated={ __( 'My feature activated' ) }
                        messageDeactivated={ __( 'My feature deactivated' ) }
                    />
                </MenuGroup>
            ) }
        </MoreMenuDropdown>
    );
}

API Reference

Actions

The following set of dispatching action creators are available on the object returned by wp.data.dispatch( 'core/preferences' ):

set

Returns an action object used in signalling that a preference should be set to a value

Parameters

• scope string: The preference scope (e.g. core/edit-post).
• name string: The preference name.
• value *: The value to set.

Returns

• Object: Action object.

setDefaults

Returns an action object used in signalling that preference defaults should be set.

Parameters

• scope string: The preference scope (e.g. core/edit-post).
• defaults Object<string, *>: A key/value map of preference names to values.

Returns

• Object: Action object.

toggle

Returns an action object used in signalling that a preference should be toggled.

Parameters

• scope string: The preference scope (e.g. core/edit-post).
• name string: The preference name.

Selectors

The following selectors are available on the object returned by wp.data.select( 'core/preferences' ):

get

Returns a boolean indicating whether a prefer is active for a particular scope.

Parameters

• state Object: The store state.
• scope string: The scope of the feature (e.g. core/edit-post).
• name string: The name of the feature.

Returns

• *: Is the feature enabled?

Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main contributor guide.