README

Compose

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

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 such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

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.

This is just a re-export of lodash's flowRight function.

Related

https://docs-lodash.com/v4/flow-right/

createHigherOrderComponent

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

Parameters

mapComponent HigherOrderComponent< HOCProps >: Function mapping component to enhanced component.
modifierName string: Seed name from which to generated display name.

Returns

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.

Usage

type Props = { foo: string };
const Component = ( props: Props ) => <div>{ props.foo }</div>;
const ConditionalComponent = ifCondition(
    ( props: Props ) => props.foo.length !== 0
)( Component );
<ConditionalComponent foo="" />; // => null
<ConditionalComponent foo="bar" />; // => <div>bar</div>;

Parameters

predicate ( props: TProps ) => boolean: Function to test condition.

Returns

Higher-order component.

pure

Given a component returns the enhanced component augmented with a component only re-rendering when its props/state change

useAsyncList

React hook returns an array which items get asynchronously appended from a source array. This behavior is useful if we want to render a list of items asynchronously for performance reasons.

Parameters

list T[]: Source array.
config AsyncListConfig: Configuration object.

Returns

T[]: Async array.

useConstrainedTabbing

In Dialogs/modals, the tabbing must be constrained to the content of the wrapper element. This hook adds the behavior to the returned ref.

Usage

import { useConstrainedTabbing } from '@wordpress/compose';

const ConstrainedTabbingExample = () => {
    const constrainedTabbingRef = useConstrainedTabbing();
    return (
        <div ref={ constrainedTabbingRef }>
            <Button />
            <Button />
        </div>
    );
};

Returns

import('react').RefCallback<Element>: Element Ref.

useCopyOnClick

Deprecated

Copies the text to the clipboard when the element is clicked.

Parameters

ref import('react').RefObject<string | Element | NodeListOf<Element>>: Reference with the element.
text string|Function: The text to copy.
timeout [number]: Optional timeout to reset the returned state. 4 seconds by default.

Returns

boolean: Whether or not the text has been copied. Resets after the timeout.

useCopyToClipboard

Copies the given text to the clipboard when the element is clicked.

Parameters

text string | (() => string): The text to copy. Use a function if not already available and expensive to compute.
onSuccess Function: Called when to text is copied.

Returns

import('react').Ref<TElementType>: A ref to assign to the target element.

useDebounce

Debounces a function with Lodash's debounce. A new debounced function will be returned and any scheduled calls cancelled if any of the arguments change, including the function to debounce, so please wrap functions created on render in components in useCallback.

Related

https://docs-lodash.com/v4/debounce/

Parameters

fn TFunc: The function to debounce.
wait [number]: The number of milliseconds to delay.
options [import('lodash').DebounceSettings]: The options object.

Returns

import('lodash').DebouncedFunc<TFunc>: Debounced function.

useFocusableIframe

Dispatches a bubbling focus event when the iframe receives focus. Use onFocus as usual on the iframe or a parent element.

Returns

Object: Ref to pass to the iframe.

useFocusOnMount

Hook used to focus the first tabbable element on mount.

Usage

import { useFocusOnMount } from '@wordpress/compose';

const WithFocusOnMount = () => {
    const ref = useFocusOnMount();
    return (
        <div ref={ ref }>
            <Button />
            <Button />
        </div>
    );
};

Parameters

focusOnMount boolean | 'firstElement': Focus on mount mode.

Returns

import('react').RefCallback<HTMLElement>: Ref callback.

useFocusReturn

When opening modals/sidebars/dialogs, the focus must move to the opened area and return to the previously focused element when closed. The current hook implements the returning behavior.

Usage

import { useFocusReturn } from '@wordpress/compose';

const WithFocusReturn = () => {
    const ref = useFocusReturn();
    return (
        <div ref={ ref }>
            <Button />
            <Button />
        </div>
    );
};

Parameters

onFocusReturn [() => void]: Overrides the default return behavior.

Returns

import('react').RefCallback<HTMLElement>: Element Ref.

useInstanceId

Provides a unique instance ID.

Parameters

object object: Object reference to create an id for.
prefix [string]: Prefix for the unique id.
preferredId [string | number]: Default ID to use.

Returns

string | number: The unique instance id.

useIsomorphicLayoutEffect

Preferred over direct usage of useLayoutEffect when supporting server rendered components (SSR) because currently React throws a warning when using useLayoutEffect in that environment.

useKeyboardShortcut

Attach a keyboard shortcut handler.

Related

https://craig.is/killing/mice#api.bind for information about the callback parameter.

Parameters

shortcuts string[]|string: Keyboard Shortcuts.
callback (e: import('mousetrap').ExtendedKeyboardEvent, combo: string) => void: Shortcut callback.
options WPKeyboardShortcutConfig: Shortcut options.

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.

useMergeRefs

Merges refs into one ref callback.

It also ensures that the merged ref callbacks are only called when they change (as a result of a useCallback dependency update) OR when the ref value changes, just as React does when passing a single ref callback to the component.

As expected, if you pass a new function on every render, the ref callback will be called after every render.

If you don't wish a ref callback to be called after every render, wrap it with useCallback( callback, dependencies ). When a dependency changes, the old ref callback will be called with null and the new ref callback will be called with the same value.

To make ref callbacks easier to use, you can also pass the result of useRefEffect, which makes cleanup easier by allowing you to return a cleanup function instead of handling null.

It's also possible to disable a ref (and its behaviour) by simply not passing the ref.

const ref = useRefEffect( ( node ) => {
  node.addEventListener( ... );
  return () => {
    node.removeEventListener( ... );
  };
}, [ ...dependencies ] );
const otherRef = useRef();
const mergedRefs useMergeRefs( [
  enabled && ref,
  otherRef,
] );
return <div ref={ mergedRefs } />;

Parameters

refs Array<TRef>: The refs to be merged.

Returns

import('react').RefCallback<TypeFromRef<TRef>>: The merged ref callback.

usePrevious

Use something's value from the previous render. Based on https://usehooks.com/usePrevious/.

Parameters

value T: The value to track.

Returns

T | undefined: The value from the previous render.

useReducedMotion

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

Returns

boolean: Reduced motion preference value.

useRefEffect

Effect-like ref callback. Just like with useEffect, this allows you to return a cleanup function to be run if the ref changes or one of the dependencies changes. The ref is provided as an argument to the callback functions. The main difference between this and useEffect is that the useEffect callback is not called when the ref changes, but this is. Pass the returned ref callback as the component's ref and merge multiple refs with useMergeRefs.

It's worth noting that if the dependencies array is empty, there's not strictly a need to clean up event handlers for example, because the node is to be removed. It is necessary if you add dependencies because the ref callback will be called multiple times for the same node.

Parameters

callback ( node: TElement ) => ( () => void ) | undefined: Callback with ref as argument.
dependencies DependencyList: Dependencies of the callback.

Returns

RefCallback< TElement | null >: Ref callback.

useResizeObserver

Hook which allows to listen the resize event of any target element when it changes sizes. Note: useResizeObserver will report null until after first render

Simply a re-export of react-resize-aware so refer to its documentation https://github.com/FezVrasta/react-resize-aware for more details.

Related

https://github.com/FezVrasta/react-resize-aware

Usage

const App = () => {
    const [ resizeListener, sizes ] = useResizeObserver();

    return (
        <div>
            { resizeListener }
            Your content here
        </div>
    );
};

useThrottle

Throttles a function with Lodash's throttle. A new throttled function will be returned and any scheduled calls cancelled if any of the arguments change, including the function to throttle, so please wrap functions created on render in components in useCallback.

Related

https://docs-lodash.com/v4/throttle/

Parameters

fn TFunc: The function to throttle.
wait [number]: The number of milliseconds to throttle invocations to.
options [import('lodash').ThrottleSettings]: The options object. See linked documentation for details.

Returns

import('lodash').DebouncedFunc<TFunc>: Throttled function.

useViewportMatch

Returns true if the viewport matches the given query, or false otherwise.

Usage

useViewportMatch( 'huge', '<' );
useViewportMatch( 'medium' );

Parameters

breakpoint WPBreakpoint: Breakpoint size name.
operator [WPViewportOperator]: Viewport operator.

Returns

boolean: Whether viewport matches query.

useWarnOnChange

Hook that performs a shallow comparison between the preview value of an object and the new one, if there's a difference, it prints it to the console. this is useful in performance related work, to check why a component re-renders.

Usage

function MyComponent( props ) {
    useWarnOnChange( props );

    return 'Something';
}

Parameters

object object: Object which changes to compare.
prefix string: Just a prefix to show when console logging.

withGlobalEvents

Deprecated

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 Record<keyof GlobalEventHandlersEventMap, 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

any: Higher-order component.

withInstanceId

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

withSafeTimeout

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

withState

Deprecated Use useState instead.

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

Parameters

initialState any: Optional initial state of the component.

Returns

any: A higher order component wrapper accepting a component that takes the state props + its own props + setState and returning a component that only accepts the own props.

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.

Code is Poetry.

Usage no npm install needed!

README

Compose

Installation

API

compose

createHigherOrderComponent

ifCondition

pure

useAsyncList

useConstrainedTabbing

useCopyOnClick

useCopyToClipboard

useDebounce

useFocusableIframe

useFocusOnMount

useFocusReturn

useInstanceId

useIsomorphicLayoutEffect

useKeyboardShortcut

useMediaQuery

useMergeRefs

usePrevious

useReducedMotion

useRefEffect

useResizeObserver

useThrottle

useViewportMatch

useWarnOnChange

withGlobalEvents

withInstanceId

withSafeTimeout

withState

Contributing to this package