A library of useful hooks.
npm install @rennalabs/hooks
A library of react hooks for state and UI management.
> Note: React 16.8+ is required for Hooks.
#### With npm
``sh`
npm i @rennalabs/hooks --save
#### Or with yarn
`sh`
yarn add @rennalabs/hooks
- Hooks
- useNetworkStatus()
- useWindowScrollPosition()
- useWindowSize()
- useLocalStorage()
- useOnClickOutside()
- useMediaQuery()
- usePrefersReducedMotion()
- useTimeout()
- useInterval()
- useRandomInterval()
- useCounter()
- useHover()
- useOs()
- useMousePosition()
- useFullscreen()
- useIdle()
- useCookie()
- useDocumentTitle()
- useDocumentVisibility()
- useGeolocation()
- useIsomorphicEffect()
- useWindowEvent()
- useFavicon()
- useDidUpdate()
- useLogger()
Retrieve network status from the browser.
#### Returns
Object containing:
- isOnline: boolean: true if the browser has network access. false
otherwise.
- offlineAt?: Date: Date when network connection was lost.
#### Example
`js
import { useNetworkStatus } from '@rennalabs/hooks';
const Example = () => {
const { isOnline, offlineAt } = useNetworkStatus();
return (
}
$3
#### Returns
Object containing:
-
x: number: Horizontal scroll in pixels (window.pageXOffset).
- y: number: Vertical scroll in pixels (window.pageYOffset).#### Example
`js
import { useWindowScrollPosition } from '@rennalabs/hooks';const Example = () => {
const { x, y } = useWindowScrollPosition();
return
{Scroll position is { x: ${x}, y: ${y} }};
};
`$3
#### Returns
Object containing:
-
width: Width of browser viewport (window.innerWidth)
- height: Height of browser viewport (window.innerHeight)#### Example
`js
import { useWindowSize } from '@rennalabs/hooks';const Example = () => {
const { width, height } = useWindowSize();
return
{window size is ${width}x${height}};
};
`$3
Allows you to use value from localStorage as react state. Hook works the same way as useState, but also writes the value to localStorage. Subscribes to the
storage event. When state changes in one tab, it automatically updates value in all other opened browser tabs.#### Arguments
-
key: string: Key to the value in local storage
- defaultValue: string: Default value for the provided key#### Returns
Array containing:
-
value: string: Value to the key in localStorage.
- setValue: function: Setter function to the provided key
- removeValue: function: Callback to remove key/value from localStorage#### Example
`js
import { useLocalStorage } from '@rennalabs/hooks';const Example = () => {
// Similar to useState but first arg is key
// to the value in local storage.
const [value, setValue, removeValue] = useLocalStorage('keyName', 'keyValue');
return (
{Saved value: ${value}}
setValue(e.target.value)} />
);
};
`$3
Detects click and touch events outside of specified element and fires given callback function.
#### Arguments
-
handler: function: function that will be called on outside click.
- events?: string[]: optional list of events that indicate outside click.
- nodes?: HTMLElement[]: optional list of nodes that should not trigger outside click event.#### Returns
-
ref: React ref object that should be passed to element on which outside clicks should be captured.#### Example
`js
import { useState } from 'react';
import { useOnClickOutside } from '@rennalabs/hooks';function Demo() {
const [opened, setOpened] = useState(false);
const ref = useOnClickOutside(() => setOpened(false));
return (
<>
{opened && (
Click outside to close
)}
>
);
}
`#### Example with Events
`js
import { useState } from 'react';
import { useOnClickOutside } from '@rennalabs/hooks';function Demo() {
const [opened, setOpened] = useState(false);
const ref = useClickOutside(() => setOpened(false), ['mouseup', 'touchend']);
return (
<>
{opened && (
Click outside to close
)}
>
);
}
`#### Example with nodes
`js
import { useState } from 'react';
import { useOnClickOutside } from '@rennalabs/hooks';function Demo() {
const [dropdown, setDropdown] = useState(null);
const [control, setControl] = useState(null);
useClickOutside(() => console.log('clicked outside'), null, [control, dropdown]);
return (
Control
Dropdown
);
}
`$3
Accepts a media query string then uses the matchMedia API to determine if it matches with the current document.
#### Arguments
-
mediaQuery: string#### Returns
-
match: boolean#### Example
`js
import { useMediaQuery } from '@rennalabs/hooks';const Example = () => {
const isSmall = useMediaQuery('(max-width: 48rem)');
const isLarge = useMediaQuery('(min-width: 48rem)');
return (
Small view? {isSmall ? 'yes' : 'no'}
Large view? {isLarge ? 'yes' : 'no'}
);
};
`$3
A hook to allow access to the CSS media query
prefers-reduced-motion.#### Returns
-
match: boolean#### Example
`js
import { usePrefersReducedMotion } from '@rennalabs/hooks';const Example = ({ isBig }) => {
const prefersReducedMotion = usePrefersReducedMotion();
const styles = {
transform: isBig ? 'scale(2)' : 'scale(1)',
transition: prefersReducedMotion ? undefined : 'transform 300ms',
};
return Stuff ;
};
`$3
A declarative adaptation of
setTimeout based on Dan Abramov's blog post about setInterval#### Arguments
-
callback: function
- delay: number#### Example
`js
import { useTimeout } from '@rennalabs/hooks';function Example() {
const [message, setMessage] = useState('changing in 2 seconds...');
useTimeout(() => setMessage('changed!'), 2000);
return {message} ;
}
`$3
A hook wrapper around window.setInterval
#### Arguments
-
callback: function
- delay: number#### Returns
Object containing:
-
start: function
- stop: function
- toggle: function
- active: boolean#### Example
`js
import { useState, useEffect } from 'react';
import { useInterval } from '@rennalabs/hooks';function Demo() {
const [seconds, setSeconds] = useState(0);
const interval = useInterval(() => setSeconds(s => s + 1), 1000);
useEffect(() => {
interval.start();
return interval.stop;
}, []);
return (
Page loaded {seconds} seconds ago
);
}
`$3
A hook itended for animations and microinteractions that fire on a spontaneous interval.
#### Arguments
-
callback: function
- minDelay?: number
- maxDelay?: number#### Returns
-
interval: number: Randomized interval between given min and max delay.#### Example
`js
import { useState, useEffect } from 'react';
import { useRandomInterval } from '@rennalabs/hooks';function LaggyTimer() {
// Update between every 1 and 4 seconds
const delay = [1000, 4000];
const [seconds, setSeconds] = useState(0);
const interval = useRandomInterval(() => setSeconds(s => s + 1), ...delay);
useEffect(() => {
interval.start();
return interval.stop;
}, []);
return (
It has been {seconds} seconds.
);
}
`$3
Increment/decrement state within given boundaries.
#### Arguments
-
initialCount: number
- clamp: { min: number; max: number; }#### Returns
Array containing
-
count: number
- handlers: object: functions to increment, decrement, reset, and set counter.#### Example
`js
import { useCounter } from '@rennalabs/hooks';function Demo() {
const [count, handlers] = useCounter(0, { min: 0, max: 10 });
return (
<>
Count: {count}
>
);
}
`$3
Detect if mouse is over given element.
#### Returns
Object containing
-
hovered: boolean: Element's hover state.
- ref: object: React ref object to attach to element.#### Example
`js
import { useHover } from '@rennalabs/hooks';function Demo() {
const { hovered, ref } = useHover();
return
{hovered ? 'I am hovered' : 'Hover over me please'};
}
`$3
useOs detects user's operating system. Possible values are: undetermined, macos, ios, windows, android, linux. If os cannot be identified, for example, during server side rendering undetermined will be returned.
#### Returns
os: undetermined | macos | ios | windows | android | linux#### Example
`js
import { useOs } from '@rennalabs/hooks';function Demo() {
const os = useOs();
return (
<>
Your operating system is {os}
>
);
}
`$3
Get mouse position relative to viewport or given element.
#### Returns
Object containing
-
ref: object: React ref object to attach to element.
- x: number: X coordinate of element.
- y: number: Y coordinate of element.#### Example
`js
import { useMousePosition } from '@rennalabs/hooks';function Demo() {
const { ref, x, y } = useMousePosition();
return (
<>
Mouse coordinates are {
{ x: ${x}, y: ${y} }}
>
);
}
`$3
useFullscreen allows to enter/exit fullscreen for given element using the Fullscreen API. By default, if you don't provide ref, hook will target document.documentElement:
#### Returns
Object containing:
-
toggle: function: Function to toggle fullscreen.
- fullscreen: boolean: Fullscreen status.
- ref: object: React ref object to attach to custom element to make fullscreen.#### Example
`js
import { useFullscreen } from '@rennalabs/hooks';function Demo() {
const { toggle, fullscreen } = useFullscreen();
return (
);
}
`#### Example with custom element
`js
import { useFullscreen } from '@rennalabs/hooks';function Demo() {
const { ref, toggle, fullscreen } = useFullscreen();
return (
<>
ref={ref}
src="https://unsplash.com/image.jpg"
alt="Unsplash Image to make Fullscreen"
width={200}
/>
>
);
}
`$3
Detects if user does nothing for given time in ms:
#### Arguments
-
idleCount: number: number of ms to determine if user is idle.#### Returns
-
idle: boolean: Is user idle.#### Example
`js
import { useIdle } from '@rennalabs/hooks';function Demo() {
const idle = useIdle(2000);
return
Current state: {idle ? 'idle' : 'not idle'};
}
`$3
React hook wrapper for js-cookie
#### Arguments
-
key: string: Name of cookie.#### Returns
Array containing
-
value: any: Current value of cookie.
- updateCookie: function: Callback to update the cookie.
- deleteCookie: function: Callback to delete the cookie.#### Example
`js
import { useCookie } from '@rennalabs/hooks';function Demo() {
const [value, updateCookie, deleteCookie] = useCookie('my-cookie');
const updateCookieHandler = () => {
updateCookie('new-cookie-value');
};
return (
Value: {value}
);
}
`$3
Sets document.title property with React's useLayoutEffect hook. Hook is not called during server side rendering. Use this hook with client only applications. Call hook with string that should be set as document title inside any component. Hook is triggered every time value changes and value is not empty string (trailing whitespace is trimmed) or null.
#### Arguments
-
title: string#### Example
`js
import { useState } from 'react';
import { useDocumentTitle } from '@rennalabs/hooks';function Demo() {
const [title, setTitle] = useState('');
useDocumentTitle(title);
return ;
}
`$3
Returns current document.visibilityState – it allows to detect if current tab is active.
#### Returns
-
documentState: visible | hidden#### Example
`js
import { useDocumentTitle, useDocumentVisibility } from '@rennalabs/hooks';function Demo() {
const documentState = useDocumentVisibility();
useDocumentTitle(
Document is ${documentState}); return
Switch to another tab to see document title change;
}
`$3
Returns user's geographic location. This hook accepts position options.
#### Arguments
-
options?: PositionOptions#### Returns
Object containing:
-
loading: boolean
- accuracy: number | null
- altitude: number | null
- altitudeAccuracy: number | null
- heading: number | null
- latitude: number | null
- longitude: number | null
- speed: number | null
- timestamp: number | null
- error?: Error#### Example
`js
import { useGeolocation } from '@rennalabs/hooks';function Demo() {
const { loading, error, latitude, longitude } = useGeolocation();
if (loading) return 'loading...';
if (error) return 'error';
return (
Your location is {latitude} x {longitude}
);
}
`$3
Allows you to switch between useEffect during server side rendering and useLayoutEffect after hydration. Use it wherever you would use useLayoutEffect to avoid warnings during ssr.
$3
-
callback: function
- dependencies?: any[]#### Example
`js
import { useIsomorphicEffect } from '@rennalabs/hooks';function Demo() {
useIsomorphicEffect(() => {
document.title = 'title';
});
return null;
}
`$3
Adds an event listener to
window object on component mount and removes it on unmount:#### Arguments
-
key: string: Any type found in WindowEventMap
- callback: function: Handler function to pass to event listener.#### Example
`js
import { useEffect } from 'react';
import { useWindowEvent } from '@rennalabs/hooks';const handler = event => console.log(event);
// regular way
useEffect(() => {
window.addEventListener('keydown', handler);
return () => window.removeEventListener('keydown', handler);
}, []);
// with useWindowEvent hook
useWindowEvent('keydown', handler);
`$3
Appends a
element to head component with given favicon in React.useLayoutEffect hook. Hook is not called during server side rendering.#### Arguments
-
url: string: Favicon url (supported formats: .ico, .png, .svg and .gif). Hook is triggered every time url changes and value is not empty string (trailing whitespace is trimmed) or null.#### Example
`js
import { useState } from 'react';
import { useFavicon } from '@rennalabs/hooks';function Demo() {
const [favicon, setFavicon] = useState('https://rennalabs.xyz/favicon.ico');
const setTwitterFavicon = () => setFavicon('https://twitter.com/favicon.ico');
const setRennaLabsFavicon = () => setFavicon('https://rennalabs.xyz/favicon.ico');
useFavicon(favicon);
return (
);
}
`$3
Calls a given callback function when the component updates but not on the initial mount.
#### Arguments
-
fn: function: Callback to be fired on update
- dependencies: any[]: useEffect dependencies to watch for updates#### Example
`js
useDidUpdate(() => console.log("Won't be called when mounted"), [value]);
`$3
Logs given values to console each time component renders, do not use in production.
#### Arguments
-
name: string: Component name
- props: any[]: Array of props to log on update#### Example
`js
import { useState } from 'react';
import { useLogger } from '@rennalabs/hooks';function Demo() {
const [count, setCount] = useState(0);
useLogger('Demo', [{ count, hello: 'world' }]);
return ;
}
``---

MIT License