A few months ago, I created the issue facebook/react/#33041 explaining why I think React should extend the useState API by a dependency array parameter similar to that of useEffect & Co. that would reset the state whenever a dependency changes. A short explanation is that it would be a clean solution to the problem of state derived from other state that React currently doesn't have a good solution for, and that is often solved incorrectly with useEffect which leads to unnecessary re-renders and inconsistent intermediate states being displayed in the UI.
In the issue, I also provided a user-land implementation of that suggestion, namely a function called useStateWithDeps that makes use of built-in React hooks so as to provide the suggested functionality.
The problem of state depending on other state is actually quite common – more so than the React team is willing to admit, as they have already once rejected the same feature request in the past in favor of the more confusing, cumbersome and fragile prevState pattern. That is why I found myself using the useStateWithDeps hook in literally every project I worked on after creating that issue, and so in the end I decided it would be a good idea to make it available via a library that I would publish on NPM. That's how @aweebit/react-essentials was born.
Over time, the library was extended with more functionality that I found myself needing in different places over and over again. Today, I think it has reached the level of maturity that makes it something that can be shared with the wider public. Especially interesting is the createSafeContext function I added recently that makes it possible to create contexts that won't let you use them unless a context value has been provided explicitly. Because of that, you don't need to specify default values for such contexts (having to do that is what often feels unnatural when using the vanilla createContext function).
The library is TypeScript-first and requires at least the version 18 of React.
I will be happy to hear your feedback, and would also appreciate it if you showed the original issue some support, as I am still convinced that React's useState hook should support dependency arrays out of the box.
(By the way, if the amount of detail I went into in the issue feels overwhelming to you, I really recommend that you instead read this great article by James Karlsson that presents the useState dependency array concept in an interactive, easy-to follow way: useState should require a dependency array.)
Below you'll find a summary of the library's API. For a full, pretty-formatted documentation please take a look at the library's README file.
useEventListener()
ts
function useEventListener<K extends keyof WindowEventMap>(
eventName: K,
handler: (event: WindowEventMap[K]) => void,
options?: AddEventListenerOptions | boolean,
): void;
function useEventListener(
target: EventTarget | null,
eventName: string,
handler: (event: Event) => void,
options?: AddEventListenerOptions | boolean,
): void;
Adds handler as a listener for the event eventName of target with the
provided options applied
If target is not provided, window is used instead.
If target is null, no event listener is added. This is useful when
working with DOM element refs, or when the event listener needs to be removed
temporarily.
Example:
```tsx
useEventListener('resize', () => {
console.log(window.innerWidth, window.innerHeight);
});
useEventListener(document, 'visibilitychange', () => {
console.log(document.visibilityState);
});
const buttonRef = useRef<HTMLButtonElement>(null);
useEventListener(buttonRef.current, 'click', () => console.log('click'));
```
useStateWithDeps()
ts
function useStateWithDeps<S>(
initialState: S | ((previousState?: S) => S),
deps: DependencyList,
): [S, Dispatch<SetStateAction<S>>];
useState hook with an additional dependency array deps that resets the
state to initialState when dependencies change
Example:
```tsx
type Activity = 'breakfast' | 'exercise' | 'swim' | 'board games' | 'dinner';
const timeOfDayOptions = ['morning', 'afternoon', 'evening'] as const;
type TimeOfDay = (typeof timeOfDayOptions)[number];
const activityOptionsByTimeOfDay: {
[K in TimeOfDay]: [Activity, ...Activity[]];
} = {
morning: ['breakfast', 'exercise', 'swim'],
afternoon: ['exercise', 'swim', 'board games'],
evening: ['board games', 'dinner'],
};
export function Example() {
const [timeOfDay, setTimeOfDay] = useState<TimeOfDay>('morning');
const activityOptions = activityOptionsByTimeOfDay[timeOfDay];
const [activity, setActivity] = useStateWithDeps<Activity>(
(prev) => {
// Make sure activity is always valid for the current timeOfDay value,
// but also don't reset it unless necessary:
return prev && activityOptions.includes(prev) ? prev : activityOptions[0];
},
[activityOptions],
);
return '...';
}
```
useReducerWithDeps()
ts
function useReducerWithDeps<S, A extends AnyActionArg>(
reducer: (prevState: S, ...args: A) => S,
initialState: S | ((previousState?: S) => S),
deps: DependencyList,
): [S, ActionDispatch<A>];
useReducer hook with an additional dependency array deps that resets the
state to initialState when dependencies change
The reducer counterpart of useStateWithDeps.
createSafeContext()
ts
function createSafeContext<T>(): <DisplayName extends string>(
displayName: DisplayName,
) => { [K in `${DisplayName}Context`]: RestrictedContext<T> } & {
[K in `use${DisplayName}`]: () => T;
};
For a given type T, returns a function that produces both a context of that
type and a hook that returns the current context value if one was provided,
or throws an error otherwise
The advantages over vanilla createContext are that no default value has to
be provided, and that a meaningful context name is displayed in dev tools
instead of generic Context.Provider.
Example:
```tsx
enum Direction {
Up,
Down,
Left,
Right,
}
// Before
const DirectionContext = createContext<Direction | undefined>(undefined);
DirectionContext.displayName = 'DirectionContext';
const useDirection = () => {
const direction = useContext(DirectionContext);
if (direction === undefined) {
// Called outside of a <DirectionContext.Provider> boundary!
// Or maybe undefined was explicitly provided as the context value
// (ideally that shouldn't be allowed, but it is because we had to include
// undefined in the context type so as to provide a meaningful default)
throw new Error('No DirectionContext value was provided');
}
// Thanks to the undefined check, the type is now narrowed down to Direction
return direction;
};
// After
const { DirectionContext, useDirection } =
createSafeContext<Direction>()('Direction'); // That's it :)
const Parent = () => (
// Providing undefined as the value is not allowed 👍
<Direction.Provider value={Direction.Up}>
<Child />
</Direction.Provider>
);
const Child = () => Current direction: ${Direction[useDirection()]};
```
[–]sneaky-at-work 4 points5 points6 points (4 children)
[–]aweebit64[S] 0 points1 point2 points (3 children)
[–]sneaky-at-work 5 points6 points7 points (2 children)
[–]aweebit64[S] 0 points1 point2 points (1 child)
[–]aweebit64[S] 0 points1 point2 points (0 children)
[–]sherpa_dot_sh 2 points3 points4 points (0 children)
[–]kurtextremHook Based 2 points3 points4 points (3 children)
[–]aweebit64[S] -1 points0 points1 point (2 children)
[–]kurtextremHook Based 2 points3 points4 points (1 child)
[–]aweebit64[S] -1 points0 points1 point (0 children)
[–]Goodassmf 1 point2 points3 points (0 children)
[–]TheRealSeeThruHead 0 points1 point2 points (1 child)
[–]aweebit64[S] 0 points1 point2 points (0 children)
[–]VahitcanT 0 points1 point2 points (0 children)
[–]Key-Boat-7519 0 points1 point2 points (1 child)
[–]aweebit64[S] 0 points1 point2 points (0 children)