state-hooks

Essential set of React Hooks for convenient state management.

Key features

Being part of the @kripod/react-hooks project, this package is:

• 🌳 Bundler-friendly with tree shaking support
• 📚 Well-documented and type-safe interfaces
• ⚛️ Zero-config server-side rendering capability
• 📦 Self-contained, free of runtime dependencies

Usage

After installing the package, import individual hooks as shown below:

import { usePrevious, useUndoable } from 'state-hooks';

Reference

Table of Contents

• useChanging
• usePrevious
• useTimeline
• useToggle
• useUndoable

useChanging

Tracks whether a value has changed over a relatively given period of time.

Parameters

• value T Props, state or any other calculated value.
• groupingIntervalMs number Time interval, in milliseconds, to group a batch of changes by. (optional, default 150)

Examples

function Component() {
  const scrollCoords = useWindowScrollCoords();
  const isScrolling = useChanging(scrollCoords);
  // ...
}

Returns boolean true if the value has changed at least once over the given interval, or false otherwise.

usePrevious

Tracks previous state of a value.

Parameters

• value T Props, state or any other calculated value.

Examples

function Component() {
  const [count, setCount] = useState(0);
  const prevCount = usePrevious(count);
  // ...
  return `Now: ${count}, before: ${prevCount}`;
}

Returns (T | undefined) Value from the previous render of the enclosing component.

useTimeline

Records states of a value over time.

Parameters

• value T Props, state or any other calculated value.
• maxLength number Maximum amount of states to store at once. Should be an integer greater than 1. (optional, default MAX_SMALL_INTEGER)

Examples

function Component() {
  const [count, setCount] = useState(0);
  const counts = useTimeline(count);
  // ...
  return `Now: ${count}, history: ${counts}`;
}

Returns ReadonlyArray<T> Results of state updates in chronological order.

useToggle

Wraps a state hook to add boolean toggle functionality.

Parameters

• useStateResult [boolean, React.Dispatch<React.SetStateAction<boolean>>] Return value of a state hook.
  • useStateResult.0 Current state.
  • useStateResult.1 State updater function.

Examples

function Component() {
  const [isPressed, setPressed, togglePressed] = useToggle(
    useState < boolean > false,
  );
  // ...
  return (
    <button type="button" aria-pressed={isPressed} onClick={togglePressed}>
      Toggle state
    </button>
  );
}

Returns [boolean, React.Dispatch<React.SetStateAction<boolean>>, function (): void] State hook result extended with a toggle function.

useUndoable

Wraps a state hook to add undo/redo functionality.

Parameters

• useStateResult [T, React.Dispatch<React.SetStateAction<T>>] Return value of a state hook.
  • useStateResult.0 Current state.
  • useStateResult.1 State updater function.
• maxDeltas number Maximum amount of state differences to store at once. Should be a positive integer. (optional, default MAX_SMALL_INTEGER)

Examples

function Component() {
  const [value, setValue, { undo, redo, past, future }] = useUndoable(
    useState(''),
  );
  // ...
  return (
    <>
      <button type="button" onClick={undo} disabled={past.length === 0}>
        Undo
      </button>
      <input value={value} onChange={(event) => setValue(event.target.value)} />
      <button type="button" onClick={redo} disabled={future.length === 0}>
        Redo
      </button>
    </>
  );
}

Returns [T, React.Dispatch<React.SetStateAction<T>>, {undo: function (): void, redo: function (): void, past: Array<T>, future: Array<T>, jump: function (delta: number): void}] State hook result extended with an object containing undo, redo, past, future and jump.