@wordpress/compose Edit

The compose package is a collection of handy Hooks and Higher Order Components (HOCs) you can use to wrap your WordPress components and provide some basic features like: state, instance id, pure…

The compose function is an alias to flowRight from Lodash. It comes from functional programming, and allows you to compose any number of functions. You might also think of this as layering functions; compose will execute the last function first, then sequentially move back through the previous functions passing the result of each function upward.

An example that illustrates it for two functions:

const compose = ( f, g ) => x
    => f( g( x ) );

Here’s a simplified example of compose in use from Gutenberg’s PluginSidebar component:

Using compose:

const applyWithSelect = withSelect( ( select, ownProps ) => {
    return doSomething( select, ownProps);
} );
const applyWithDispatch = withDispatch( ( dispatch, ownProps ) => {
    return doSomethingElse( dispatch, ownProps );
} );

export default compose(
    withPluginContext,
    applyWithSelect,
    applyWithDispatch,
)( PluginSidebarMoreMenuItem );

Without compose, the code would look like this:

const applyWithSelect = withSelect( ( select, ownProps ) => {
    return doSomething( select, ownProps);
} );
const applyWithDispatch = withDispatch( ( dispatch, ownProps ) => {
    return doSomethingElse( dispatch, ownProps );
} );

export default withPluginContext(
    applyWithSelect(
        applyWithDispatch(
            PluginSidebarMoreMenuItem
        )
    )
);

Installation Installation

Install the module

npm install @wordpress/compose --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 ↑

API API

For more details, you can refer to each Higher Order Component’s README file. Available components are located here.

# compose

Composes multiple higher-order components into a single higher-order component. Performs right-to-left function
composition, where each successive invocation is supplied the return value of the previous.

Parameters

  • hocs ...Function: The HOC functions to invoke.

Returns

  • Function: Returns the new composite function.

# createHigherOrderComponent

Given a function mapping a component to an enhanced component and modifier
name, returns the enhanced component augmented with a generated displayName.

Parameters

  • mapComponentToEnhancedComponent Function: Function mapping component to enhanced component.
  • modifierName string: Seed name from which to generated display name.

Returns

  • WPComponent: Component class with generated display name assigned.

# ifCondition

Higher-order component creator, creating a new component which renders if
the given condition is satisfied or with the given optional prop name.

Parameters

  • predicate Function: Function to test condition.

Returns

  • Function: Higher-order component.

# pure

Given a component returns the enhanced component augmented with a component
only rerendering when its props/state change

Parameters

  • mapComponentToEnhancedComponent Function: Function mapping component to enhanced component.
  • modifierName string: Seed name from which to generated display name.

Returns

  • WPComponent: Component class with generated display name assigned.

# useMediaQuery

Runs a media query and returns its value when it changes.

Parameters

  • query string: Media Query.

Returns

  • boolean: return value of the media query.

# useReducedMotion

Hook returning whether the user has a preference for reduced motion.

Returns

  • boolean: Reduced motion preference value.

# withGlobalEvents

Higher-order component creator which, given an object of DOM event types and
values corresponding to a callback function name on the component, will
create or update a window event handler to invoke the callback when an event
occurs. On behalf of the consuming developer, the higher-order component
manages unbinding when the component unmounts, and binding at most a single
event handler for the entire application.

Parameters

  • eventTypesToHandlers Object<string,string>: Object with keys of DOM event type, the value a name of the function on the original component’s instance which handles the event.

Returns

  • Function: Higher-order component.

# withInstanceId

A Higher Order Component used to be provide a unique instance ID by
component.

Parameters

  • WrappedComponent WPElement: The wrapped component.

Returns

  • Component: Component with an instanceId prop.

# withSafeTimeout

A higher-order component used to provide and manage delayed function calls
that ought to be bound to a component’s lifecycle.

Parameters

  • OriginalComponent Component: Component requiring setTimeout

Returns

  • Component: Wrapped component.

# withState

A Higher Order Component used to provide and manage internal component state
via props.

Parameters

  • initialState ?Object: Optional initial state of the component.

Returns

  • Component: Wrapped component.

Code is Poetry.