react-use/docs/useStateWithHistory.md

useStateHistory

Stores defined amount of previous state values and provides handles to travel through them.

Usage

Reference

const [state, setState, stateHistory] = useStateWithHistory<S = undefined>(
  initialState?: S | (()=>S),
  historyCapacity?: number = 10,
  initialHistory?: S
);

• state, setState and initialState are exactly the same with native React's useState hook;
• historyCapacity - amount of history entries that hold by storage;
• initialHistory - if defined it will be used as initial history value, otherwise history will equals [ initialState ].
  Initial state will not be pushed to initial history.
  If entries amount is greater than historyCapacity parameter it wont be modified on init but will be trimmed on next setState;
• stateHistory - an object containing history state:
  • history: S[] - an array holding history entries. I will have the same ref all the time so pe careful with that one!;
  • position: number - current position index in history;
  • capacity: number = 10 - maximum amount of history entries;
  • back: (amount?: number) => void - go back in state history, it will cause setState invoke and component re-render.
    If first element of history reached, the call will have no effect;
  • forward: (amount?: number) => void - go forward in state history, it will cause setState invoke and component re-render.
    If last element of history reached, the call will have no effect;
  • go: (position: number) => void - go to arbitrary position in history.
    In case position is non-negative ot will count elements from beginning. Negative position will cause elements counting from the end, so go(-2) equals go(history.length - 1);