@wordpress/nux Edit

The NUX module exposes components, and wp.data methods useful for onboarding a new user to the WordPress admin interface. Specifically, it exposes tips and guides.

A tip is a component that points to an element in the UI and contains text that explains the element’s functionality. The user can dismiss a tip, in which case it never shows again. The user can also disable tips entirely. Information about tips is persisted between sessions using localStorage.

A guide allows a series of of tips to be presented to the user one by one. When a user dismisses a tip that is in a guide, the next tip in the guide is shown.

Installation Installation

Install the module

npm install @wordpress/nux --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 ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.

Top ↑

DotTip DotTip

DotTip is a React component that renders a single tip on the screen. The tip will point to the React element that DotTip is nested within. Each tip is uniquely identified by a string passed to tipId.

See the component’s README for more information.

<button onClick={ ... }>
    Add to Cart
    <DotTip tipId="acme/add-to-cart">
        Click here to add the product to your shopping cart.
    </DotTip>
</button>
}

Top ↑

Determining if a tip is visible Determining if a tip is visible

You can programmatically determine if a tip is visible using the isTipVisible select method.

const isVisible = select( 'core/nux' ).isTipVisible( 'acme/add-to-cart' );
console.log( isVisible ); // true or false

Top ↑

Manually dismissing a tip Manually dismissing a tip

dismissTip is a dispatch method that allows you to programmatically dismiss a tip.

<button
    onClick={ () => {
        dispatch( 'core/nux' ).dismissTip( 'acme/add-to-cart' );
    } }
>
    Dismiss tip
</button>

Top ↑

Disabling and enabling tips Disabling and enabling tips

Tips can be programatically disabled or enabled using the disableTips and enableTips dispatch methods. You can query the current setting by using the areTipsEnabled select method.

Calling enableTips will also un-dismiss all previously dismissed tips.

const areTipsEnabled = select( 'core/nux' ).areTipsEnabled();
return (
    <button
        onClick={ () => {
            if ( areTipsEnabled ) {
                dispatch( 'core/nux' ).disableTips();
            } else {
                dispatch( 'core/nux' ).enableTips();
            }
        } }
    >
        { areTipsEnabled ? 'Disable tips' : 'Enable tips' }
    </button>
);

Top ↑

Triggering a guide Triggering a guide

You can group a series of tips into a guide by calling the triggerGuide dispatch method. The given tips will then appear one by one.

A tip cannot be added to more than one guide.

dispatch( 'core/nux' ).triggerGuide( [ 'acme/product-info', 'acme/add-to-cart', 'acme/checkout' ] );

Top ↑

Getting information about a guide Getting information about a guide

getAssociatedGuide is a select method that returns useful information about the state of the guide that a tip is associated with.

const guide = select( 'core/nux' ).getAssociatedGuide( 'acme/add-to-cart' );
console.log( 'Tips in this guide:', guide.tipIds );
console.log( 'Currently showing:', guide.currentTipId );
console.log( 'Next to show:', guide.nextTipId );

Code is Poetry.