Essential set of React Hooks for convenient Web API consumption.
npm install web-api-hooksEssential set of [React Hooks] for convenient [Web API] consumption.
[react hooks]: https://reactjs.org/docs/hooks-intro.html
[web api]: https://developer.mozilla.org/docs/Web/API
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
[@kripod/react-hooks]: https://github.com/kripod/react-hooks
After installing the package, import individual hooks as shown below:
``javascript`
import { useGeolocation, useLocalStorage } from 'web-api-hooks';
š Explore the API with working examples
#### Table of Contents
- Sensors
- useColorSchemePreference
- useDeviceMotion
- useDeviceOrientation
- useDocumentReadiness
- useDocumentVisibility
- useFocus
- useGeolocation
- useHover
- useLanguagePreferences
- useMedia
- useMotionPreference
- useMouseCoords
- useNetworkAvailability
- useNetworkInformation
- useSize
- useViewportScale
- useViewportScrollCoords
- useViewportSize
- useWindowScrollCoords
- useWindowSize
- Storage
- useLocalStorage
- useSessionStorage
- Scheduling
- useEventListener
- useInterval
#### useColorSchemePreference
Tracks color scheme preference of the user.
##### Examples
`javascript`
function Component() {
const preferDarkMode = useColorSchemePreference() === 'dark';
// ...
}
Returns ("light" \| "dark") Preferred color scheme.
#### useDeviceMotion
Tracks acceleration and rotation rate of the device.
##### Examples
`javascript`
function Component() {
const { acceleration, rotationRate, interval } = useDeviceMotion();
// ...
}
Returns EventArgs<DeviceMotionEvent> Own properties of the last corresponding event.
#### useDeviceOrientation
Tracks physical orientation of the device.
##### Examples
`javascript`
function Component() {
const { alpha, beta, gamma } = useDeviceOrientation();
// ...
}
Returns EventArgs<DeviceOrientationEvent> Own properties of the last corresponding event.
#### useDocumentReadiness
Tracks loading state of the page.
##### Examples
`javascript`
function Component() {
const documentReadiness = useDocumentReadiness();
if (documentReadiness === 'interactive') {
// You may interact with any element of the document from now
}
// ...
}
Returns DocumentReadyState Readiness of the document, which is 'loading' by default.
#### useDocumentVisibility
Tracks visibility of the page.
##### Examples
`javascript`
function Component() {
const documentVisibility = useDocumentVisibility();
if (documentVisibility === 'hidden') {
// Reduce resource utilization to aid background page performance
}
// ...
}
Returns VisibilityState Visibility state of the document, which is 'visible' by default.
#### useFocus
Tracks focus state of an element.
##### Examples
`javascript`
function Component() {
const [isFocused, bindFocus] = useFocus();
// ...
return
}
Returns \[boolean, Readonly<{onFocus: function (): void, onBlur: function (): void}>] Whether the element has focus, and props to be spread over the element under observation.
#### useGeolocation
Tracks geolocation of the device.
##### Parameters
- options PositionOptions? Additional watching options.errorCallback
- function (error: PositionError): void? Method to execute in case of an error, e.g. when the user denies location sharing permissions.
##### Examples
`javascript`
function Component() {
const geolocation = useGeolocation();
if (geolocation) {
const { coords } = geolocation;
}
// ...
}
Returns (Position \| undefined) Locational data, or undefined when unavailable.
#### useHover
Tracks hover state of an element.
##### Parameters
- disallowTouch boolean Determines whether touch gestures should be ignored. (optional, default false)
##### Examples
`javascript`
function Component() {
const [isHovered, bindHover] = useHover();
// ...
return
}
Returns \[boolean, Readonly<{onMouseEnter: function (): void, onMouseLeave: function (): void, onTouchStart: function (): void, onTouchEnd: function (): void}>] Whether the element is hovered, and props to be spread over the element under observation.
#### useLanguagePreferences
Tracks language preferences of the user.
##### Examples
`javascript`
function Component() {
const preferredLanguages = useLanguagePreferences();
// ...
}
Returns ReadonlyArray<string> An array of BCP 47 language tags, ordered by preference with the most preferred language first.
#### useMedia
Tracks match state of a media query.
##### Parameters
- query string Media query to parse.
##### Examples
`javascript`
function Component() {
const isWidescreen = useMedia('(min-aspect-ratio: 16/9)');
// ...
}
Returns boolean true if the associated media query list matches the state of the document, or false otherwise.
#### useMotionPreference
Tracks motion intensity preference of the user.
##### Examples
`javascript`
function Component() {
const preferReducedMotion = useMotionPreference() === 'reduce';
// ...
}
Returns ("no-preference" \| "reduce") Preferred motion intensity.
#### useMouseCoords
Tracks mouse position.
##### Examples
`javascript`
function Component() {
const [mouseX, mouseY] = useMouseCoords();
// ...
}
Returns Readonly<\[number, number]> Coordinates [x, y], falling back to [0, 0] when unavailable.
#### useNetworkAvailability
Tracks information about the network's availability.
ā ļø _This attribute is inherently unreliable. A computer can be connected to a network without having internet access._
##### Examples
`javascript`
function Component() {
const isOnline = useNetworkAvailability();
// ...
}
Returns boolean false if the user agent is definitely offline, or true if it might be online.
#### useNetworkInformation
Tracks information about the device's network connection.
āļø _The underlying technology is experimental. Please be aware about browser compatibility before using this in production._
##### Examples
`javascript`
function Component() {
const networkInformation = useNetworkInformation();
if (networkInformation) {
const { effectiveType, downlink, rtt, saveData } = networkInformation;
}
// ...
}
Returns (NetworkInformation \| undefined) Connection data, or undefined when unavailable.
#### useSize
Tracks size of an element.
āļø _The underlying technology is experimental. Please be aware about browser compatibility before using this in production._
##### Parameters
- ref React.RefObject<HTMLElement> Attribute attached to the element under observation.ResizeObserverOverride
- TypeOf<ResizeObserver> Replacement for window.ResizeObserver, e.g. a polyfill.
##### Examples
`javascript`
function Component() {
const ref = useRef < HTMLElement > null;
const [width, height] = useSize(ref);
// ...
return
}
Returns Readonly<\[number, number]> Dimensions [width, height], falling back to [0, 0] when unavailable.
#### useViewportScale
Tracks visual viewport scale.
āļø _The underlying technology is experimental. Please be aware about browser compatibility before using this in production._
##### Examples
`javascript`
function Component() {
const viewportScale = useViewportScale();
// ...
}
Returns number Pinch-zoom scaling factor, falling back to 0 when unavailable.
#### useViewportScrollCoords
Tracks visual viewport scroll position.
āļø _The underlying technology is experimental. Please be aware about browser compatibility before using this in production._
##### Examples
`javascript`
function Component() {
const [viewportScrollX, viewportScrollY] = useViewportScrollCoords();
// ...
}
Returns Readonly<\[number, number]> Coordinates [x, y], falling back to [0, 0] when unavailable.
#### useViewportSize
Tracks visual viewport size.
āļø _The underlying technology is experimental. Please be aware about browser compatibility before using this in production._
##### Examples
`javascript`
function Component() {
const [viewportWidth, viewportHeight] = useViewportSize();
// ...
}
Returns Readonly<\[number, number]> Dimensions [width, height], falling back to [0, 0] when unavailable.
#### useWindowScrollCoords
Tracks window scroll position.
##### Examples
`javascript`
function Component() {
const [windowScrollX, windowScrollY] = useWindowScrollCoords();
// ...
}
Returns Readonly<\[number, number]> Coordinates [x, y], falling back to [0, 0] when unavailable.
#### useWindowSize
Tracks window size.
##### Examples
`javascript`
function Component() {
const [windowWidth, windowHeight] = useWindowSize();
// ...
}
Returns Readonly<\[number, number]> Dimensions [width, height], falling back to [0, 0] when unavailable.
#### useLocalStorage
- See: useState hook, which exposes a similar interface
Stores a key/value pair statefully in localStorage.
##### Parameters
- key string Identifier to associate the stored value with.initialValue
- (T | function (): T | null) Value used when no item exists with the given key. Lazy initialization is available by using a function which returns the desired value. (optional, default null)errorCallback
- function (error: (DOMException | TypeError)): void? Method to execute in case of an error, e.g. when the storage quota has been exceeded or trying to store a circular data structure.
##### Examples
`javascript`
function Component() {
const [visitCount, setVisitCount] =
useLocalStorage < number > ('visitCount', 0);
useEffect(() => {
setVisitCount((count) => count + 1);
}, []);
// ...
}
Returns \[T, React.Dispatch<React.SetStateAction<T>>] A statefully stored value, and a function to update it.
#### useSessionStorage
- See: useState hook, which exposes a similar interface
Stores a key/value pair statefully in sessionStorage.
##### Parameters
- key string Identifier to associate the stored value with.initialValue
- (T | function (): T | null) Value used when no item exists with the given key. Lazy initialization is available by using a function which returns the desired value. (optional, default null)errorCallback
- function (error: (DOMException | TypeError)): void? Method to execute in case of an error, e.g. when the storage quota has been exceeded or trying to store a circular data structure.
##### Examples
`javascript`
function Component() {
const [name, setName] = useSessionStorage < string > ('name', 'Anonymous');
// ...
}
Returns \[T, React.Dispatch<React.SetStateAction<T>>] A statefully stored value, and a function to update it.
#### useEventListener
- See: Event reference on MDN
Listens to an event while the enclosing component is mounted.
##### Parameters
- target EventTarget Target to listen on, possibly a DOM element or a remote service connector.type
- string Name of event (case-sensitive).callback
- EventListener Method to execute whenever the event fires.options
- AddEventListenerOptions? Additional listener characteristics.
##### Examples
`javascript`
function Component() {
useEventListener(window, 'error', () => {
console.log('A resource failed to load.');
});
// ...
}
Returns void
#### useInterval
Repeatedly calls a function with a fixed time delay between each call.
š _Timings may be inherently inaccurate, due to the implementation of setInterval under the hood._
##### Parameters
- callback function (): void Method to execute periodically.delayMs
- (number | null) Time, in milliseconds, to wait between executions of the specified function. Set to null for pausing.
##### Examples
`javascript`
function Component() {
useInterval(() => {
// Custom logic to execute each second
}, 1000);
// ...
}
Returns void
- Avoid layout thrashing by debouncing or throttling high frequency events, e.g. scrolling or mouse movements
- Move non-primitive hook parameters to an outer scope or memoize them with useMemo, e.g.:
`tsx``
const geolocationOptions = { enableHighAccuracy: true };
function Component() {
const geolocation = useGeolocation(geolocationOptions);
// ...
}