Renna Labs' Hooks

A library of react hooks for state and UI management.

Install

Note: React 16.8+ is required for Hooks.

With npm

npm i @rennalabs/hooks --save

Or with yarn

yarn add @rennalabs/hooks

API

Hooks

Hooks

`useNetworkStatus()`

View source code

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

import { useNetworkStatus } from '@rennalabs/hooks';

const Example = () => {
  const { isOnline, offlineAt } = useNetworkStatus();

  return (
    <div style={{ background: isOnline ? 'green' : 'red' }}>
      {`App went offline at ${offlineAt.toString()}`}
    </div>
  );
};

`useWindowScrollPosition()`

View source code

Returns

Object containing:

x: number: Horizontal scroll in pixels (window.pageXOffset).
y: number: Vertical scroll in pixels (window.pageYOffset).

Example

import { useWindowScrollPosition } from '@rennalabs/hooks';

const Example = () => {
  const { x, y } = useWindowScrollPosition();

  return <div>{`Scroll position is { x: ${x}, y: ${y} }`}</div>;
};

`useWindowSize()`

View source code

Returns

Object containing:

width: Width of browser viewport (window.innerWidth)
height: Height of browser viewport (window.innerHeight)

Example

import { useWindowSize } from '@rennalabs/hooks';

const Example = () => {
  const { width, height } = useWindowSize();

  return <div>{`window size is ${width}x${height}`}</div>;
};

`useLocalStorage()`

View source code

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

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 (
    <div>
      <h1>{`Saved value: ${value}`}</h1>
      <input onChange={e => setValue(e.target.value)} />
      <button onClick={removeValue}>Clear Storage</button>
    </div>
  );
};

`useOnClickOutside()`

View source code

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

import { useState } from 'react';
import { useOnClickOutside } from '@rennalabs/hooks';

function Demo() {
  const [opened, setOpened] = useState(false);
  const ref = useOnClickOutside(() => setOpened(false));

  return (
    <>
      <button onClick={() => setOpened(true)}>Open dropdown</button>

      {opened && (
        <DropDown ref={ref}>
          <span>Click outside to close</span>
        </DropDown>
      )}
    </>
  );
}

Example with Events

import { useState } from 'react';
import { useOnClickOutside } from '@rennalabs/hooks';

function Demo() {
  const [opened, setOpened] = useState(false);
  const ref = useClickOutside(() => setOpened(false), ['mouseup', 'touchend']);

  return (
    <>
      <button onClick={() => setOpened(true)}>Open dropdown</button>

      {opened && (
        <DropDown ref={ref}>
          <span>Click outside to close</span>
        </DropDown>
      )}
    </>
  );
}

Example with nodes

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 (
    <div>
      <div ref={setControl}>Control</div>
      <div>
        <div ref={setDropdown}>Dropdown</div>
      </div>
    </div>
  );
}

`useMediaQuery()`

View source code

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

import { useMediaQuery } from '@rennalabs/hooks';

const Example = () => {
  const isSmall = useMediaQuery('(max-width: 48rem)');
  const isLarge = useMediaQuery('(min-width: 48rem)');

  return (
    <Demo>
      <p>Small view? {isSmall ? 'yes' : 'no'}</p>
      <p>Large view? {isLarge ? 'yes' : 'no'}</p>
    </Demo>
  );
};

`usePrefersReducedMotion()`

View source code

A hook to allow access to the CSS media query prefers-reduced-motion.

Returns

match: boolean

Example

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 <Demo styles={styles}>Stuff</Demo>;
};

`useTimeout()`

View source code

A declarative adaptation of setTimeout based on Dan Abramov's blog post about setInterval

Arguments

callback: function
delay: number

Example

import { useTimeout } from '@rennalabs/hooks';

function Example() {
  const [message, setMessage] = useState('changing in 2 seconds...');

  useTimeout(() => setMessage('changed!'), 2000);

  return <Demo>{message}</Demo>;
}

`useInterval()`

View source code

A hook wrapper around window.setInterval

Arguments

callback: function
delay: number

Returns

Object containing:

start: function
stop: function
toggle: function
active: boolean

Example

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 (
    <div>
      <h1>
        Page loaded <b>{seconds}</b> seconds ago
      </h1>
      <button onClick={interval.toggle} style={{ color: interval.active ? 'red' : 'green' }}>
        {interval.active ? 'Stop' : 'Start'} counting
      </button>
    </div>
  );
}

`useRandomInterval()`

View source code

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

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 (
    <div>
      <h1>It has been {seconds} seconds.</h1>
      <button onClick={interval.toggle} style={{ color: interval.active ? 'red' : 'green' }}>
        {interval.active ? 'Stop' : 'Start'} counting
      </button>
    </div>
  );
}

`useCounter()`

View source code

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

import { useCounter } from '@rennalabs/hooks';

function Demo() {
  const [count, handlers] = useCounter(0, { min: 0, max: 10 });

  return (
    <>
      <h1>Count: {count}</h1>
      <div>
        <button onClick={handlers.increment}>Increment</button>
        <button onClick={handlers.decrement}>Decrement</button>
        <button onClick={handlers.reset}>Reset</button>
        <button onClick={() => handlers.set(5)}>Set 5</button>
      </div>
    </>
  );
}

`useHover()`

View source code

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

import { useHover } from '@rennalabs/hooks';

function Demo() {
  const { hovered, ref } = useHover();

  return <div ref={ref}>{hovered ? 'I am hovered' : 'Hover over me please'}</div>;
}

`useOs()`

View source code

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

Example

import { useOs } from '@rennalabs/hooks';

function Demo() {
  const os = useOs();
  return (
    <>
      Your operating system is <b>{os}</b>
    </>
  );
}

`useMousePosition()`

View source code

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

import { useMousePosition } from '@rennalabs/hooks';

function Demo() {
  const { ref, x, y } = useMousePosition();

  return (
    <>
      Mouse coordinates are <b>{`{ x: ${x}, y: ${y} }`}</b>
    </>
  );
}

`useFullscreen()`

View source code

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

import { useFullscreen } from '@rennalabs/hooks';

function Demo() {
  const { toggle, fullscreen } = useFullscreen();

  return (
    <button onClick={toggle} style={{ color: fullscreen ? 'red' : 'green' }}>
      {fullscreen ? 'Exit Fullscreen' : 'Enter Fullscreen'}
    </button>
  );
}

Example with custom element

import { useFullscreen } from '@rennalabs/hooks';

function Demo() {
  const { ref, toggle, fullscreen } = useFullscreen();

  return (
    <>
      <img
        ref={ref}
        src="https://unsplash.com/image.jpg"
        alt="Unsplash Image to make Fullscreen"
        width={200}
      />

      <button onClick={toggle} style={{ color: fullscreen ? 'red' : 'green' }}>
        {fullscreen ? 'Exit Fullscreen' : 'View Image Fullscreen'}
      </button>
    </>
  );
}

`useIdle()`

View source code

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

import { useIdle } from '@rennalabs/hooks';

function Demo() {
  const idle = useIdle(2000);

  return <div>Current state: {idle ? 'idle' : 'not idle'}</div>;
}

`useCookie()`

View source code

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

import { useCookie } from '@rennalabs/hooks';

function Demo() {
  const [value, updateCookie, deleteCookie] = useCookie('my-cookie');

  const updateCookieHandler = () => {
    updateCookie('new-cookie-value');
  };

  return (
    <div>
      <p>Value: {value}</p>
      <button onClick={updateCookieHandler}>Update Cookie</button>

      <button onClick={deleteCookie}>Delete Cookie</button>
    </div>
  );
}

`useDocumentTitle()`

View source code

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

import { useState } from 'react';
import { useDocumentTitle } from '@rennalabs/hooks';

function Demo() {
  const [title, setTitle] = useState('');
  useDocumentTitle(title);

  return <button onClick={() => setTitle('new title')}>Set document title</button>;
}

`useDocumentVisibility()`

View source code

Returns current document.visibilityState – it allows to detect if current tab is active.

Returns

documentState: visible | hidden

Example

import { useDocumentTitle, useDocumentVisibility } from '@rennalabs/hooks';

function Demo() {
  const documentState = useDocumentVisibility();
  useDocumentTitle(`Document is ${documentState}`);

  return <div>Switch to another tab to see document title change</div>;
}

`useGeolocation()`

View source code

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

import { useGeolocation } from '@rennalabs/hooks';

function Demo() {
  const { loading, error, latitude, longitude } = useGeolocation();

  if (loading) return 'loading...';
  if (error) return 'error';

  return (
    <div>
      Your location is {latitude} x {longitude}
    </div>
  );
}

`useIsomorphicEffect()`

View source code

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.

Arguments

callback: function
dependencies?: any[]

Example

import { useIsomorphicEffect } from '@rennalabs/hooks';

function Demo() {
  useIsomorphicEffect(() => {
    document.title = 'title';
  });

  return null;
}

`useWindowEvent()`

View source code

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

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);

`useFavicon()`

View source code

Appends a <link /> 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

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 (
    <div>
      <button onClick={setTwitterFavicon}>Twitter favicon</button>
      <button onClick={setRennaLabsFavicon}>Renna Labs favicon</button>
    </div>
  );
}

`useDidUpdate()`

View source code

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

useDidUpdate(() => console.log("Won't be called when mounted"), [value]);

`useLogger()`

View source code

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

import { useState } from 'react';
import { useLogger } from '@rennalabs/hooks';

function Demo() {
  const [count, setCount] = useState(0);
  useLogger('Demo', [{ count, hello: 'world' }]);

  return <button onClick={() => setCount(c => c + 1)}>Update state ({count})</button>;
}

MIT License