@aweebit/react-essentials


- useEventListener()
- useIsomorphicLayoutEffect()
- useReducerWithDeps()
- useStateWithDeps()
- contextualize()
- createSafeContext()
- wrapJSX()

$3

- React ≥ 18
- TypeScript ≥ 5.4

useEventListener

``ts
const useEventListener: UseEventListener;
`

Defined in: hooks/useEventListener.ts:136

Adds handler as a listener for the event eventName of target with the
provided options applied

The following call signatures are available:

`ts
function useEventListener(eventName, handler, options?): void;
function useEventListener(target, eventName, handler, options?): void;
`

For the full definition of the hook's type, see UseEventListener.

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.

$3

`tsx
useEventListener('resize', () => {
console.log(window.innerWidth, window.innerHeight);
});

useEventListener(document, 'visibilitychange', () => {
console.log(document.visibilityState);
});

const buttonRef = useRef(null);
useEventListener(buttonRef, 'click', () => console.log('click'));
`

$3

UseEventListener

---

useIsomorphicLayoutEffect()

`ts
const useIsomorphicLayoutEffect: (effect, deps?) => void;
`

Defined in: hooks/useIsomorphicLayoutEffect.ts:12

Identical to useLayoutEffect, except it does not result in
warnings when used on the server

$3

$3

void

---

useReducerWithDeps()

`ts
function useReducerWithDeps(
reducer,
initialState,
deps,
): [S, ActionDispatch];
`

Defined in: hooks/useReducerWithDeps.ts:64

useReducer hook with an additional dependency array deps that
resets the state to initialState when dependencies change

This hook is the reducer pattern counterpart of useStateWithDeps.

Due to React's limitations, a change in dependencies always causes two
renders when using this hook. The result of the first render is thrown away
as described in
useState > Storing information from previous renders.

For motivation and examples, see
https://github.com/facebook/react/issues/33041.

$3

The react-hooks/exhaustive-deps ESLint rule doesn't support hooks where
the dependency array parameter is at any other position than the second.
However, as we would like to keep the hook as compatible with useReducer as
possible, we don't want to artificially change the parameter's position.
Therefore, there will be no warnings about missing dependencies.
Because of that, additional caution is advised!
Be sure to check that no dependencies are missing from the deps array.

Related issue: https://github.com/facebook/react/issues/25443.

Unlike eslint-plugin-react-hooks maintained by React's team, the unofficial
useExhaustiveDependencies rule provided for Biome by Biome's team
does actually have support for dependency arrays at other positions, see
useExhaustiveDependencies \> Options \> Validating dependencies.

$3

$3

$3

\[S, ActionDispatch\<A\>\]

---

useStateWithDeps()

`ts
function useStateWithDeps(
initialState,
deps,
): [S, Dispatch>];
`

Defined in: hooks/useStateWithDeps.ts:62

useState hook with an additional dependency array deps that
resets the state to initialState when dependencies change

Due to React's limitations, a change in dependencies always causes two
renders when using this hook. The result of the first render is thrown away
as described in
useState > Storing information from previous renders.

For motivation and more examples, see
https://github.com/facebook/react/issues/33041.

$3

`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'],
};

function Example() {
const [timeOfDay, setTimeOfDay] = useState('morning');

const activityOptions = activityOptionsByTimeOfDay[timeOfDay];
const [activity, setActivity] = useStateWithDeps(
(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 '...';
}
`

$3

$3

$3

\[S, Dispatch\<SetStateAction\<S\>\>\]

---

contextualize()

`ts
function contextualize(children): ContextualizePipe;
`

Defined in: misc/contextualize.tsx:78

An alternative way to provide context values to component trees that avoids
ever-increasing indentation

A context-specific version of the more general wrapJSX function.

$3

`tsx
// Before:
return (