fast-react/packages/react/fast-react-utilities

FAST React Utilities

A set of general purpose React utilities.

Installation

npm i --save @microsoft/fast-react-utilities

Exports

Hooks

useTimeout(callback: () => void, delay: number | null, dependencies?: any[]): void

A React hook to declaratively invoke a timeout function. The callback be invoked once after delay - measured in milliseconds. Once the timeout is invoked, no other timeout will be registered unless duration changes.

To force a new timeout to be registered with a previous duration, supply new values to the dependencies. This is similar to how React's useEffect works.

Single execution of callback

function FancyButton() {
    // Execute a callback invoked after 200ms. Callback will only be called once (unless duration changes)
    useTimeout(() => {
        alert("I'm a button")
    }, 200);

    return <button>hello world</button>
}

Execute callback whenever prop is changed

function FancyButton() {
    // Execute a callback 200ms after render. A new callback will be registered
    // when props.value changes
    useTimeout((props) => {
        alert("I'm a button")
    }, 200, [props.value]);

    return <button>hello world</button>
}

Execute callback every render

import { useTransitionState, TransitionStates } from "@microsoft/fast-react-utilities";

function FancyButton() {
    // Execute a callback 200ms after every render. If render happens before the delay,
    // the previous render's timeout will be canceled.
    useTimeout(() => {
        alert("I'm a button")
    }, 200, [Symbol()]);

    return <button>hello world</button>
}

useTransitionState(active: boolean, duration: number | [number, number]): TransitionStates

A React hook used to track the state of a transition based on initial and incoming active values. useTransitionState will return a value from the TransitionStates object, representing "inactive", "active", "activating", and "deactivating". When the incoming active argument changes from one render to the next, the return value will change to one of the middle states, "activating" (false->true) or "deactivating" (true->false). After the supplied duration, the hook will invoke a setState and return the state represented by the incoming active value.

When two duration values are provided, the first will be used when activating and the second will be used when deactivating.

import { classNames } from "@microsoft/fast-web-utilities";
import { useTransitionState, TransitionStates } from "@microsoft/fast-react-utilities";

function FancyDialog(props) {
    const state = useTransitionState(props.visible, [300, 400]);

    return (
        <div
            role="dialog"
            className={classNames(
                "dialog",
                ["dialog_inactive", state === TransitionStates.inactive],
                ["dialog_active", state === TransitionStates.active],
                ["dialog_activating", state === TransitionStates.activating],
                ["dialog_deactivating", state === TransitionStates.deactivating]
            )}
            children={props.children}
        />
    );
}