@restart/hooks

Functions

• useCallbackRef()
• useCommittedRef()
• useEventCallback()
• useEventListener()
• useGlobalListener()
• useImage()
• useInterval()
• useMergeState()
• useMergeStateFromProps()
• useMounted()
• usePrevious()
• useRafInterval()
• useResizeObserver()

function useCallbackRef

useCallbackRef: <TValue = unknown>() => [TValue, (ref: TValue | null) => void];

• A convenience hook around useState designed to be paired with the component [callback ref](https://reactjs.org/docs/refs-and-the-dom.html#callback-refs) api. Callback refs are useful over useRef() when you need to respond to the ref being set instead of lazily accessing it in an effect.

  const [element, attachRef] = useCallbackRef<HTMLDivElement>()
  
  useEffect(() => {
    if (!element) return
  
    const calendar = new FullCalendar.Calendar(element)
  
    return () => {
      calendar.destroy()
    }
  }, [element])
  
  return <div ref={attachRef} />

  refs

function useCommittedRef

useCommittedRef: <TValue>(value: TValue) => React.MutableRefObject<TValue>;

• Creates a Ref whose value is updated in an effect, ensuring the most recent value is the one rendered with. Generally only required for Concurrent mode usage where previous work in render() may be discarded before being used.

  This is safe to access in an event handler.

  Parameter value

  The Ref value

function useEventCallback

useEventCallback: <TCallback extends (...args: any[]) => any>(
    fn?: TCallback | null
) => TCallback;

function useEventListener

useEventListener: <
    T extends Element | Document | Window,
    K extends keyof DocumentEventMap
>(
    eventTarget: T | (() => T),
    event: K,
    listener: EventHandler<T, K>,
    capture?: boolean | AddEventListenerOptions
) => void;

• Attaches an event handler outside directly to specified DOM element bypassing the react synthetic event system.

  Parameter element

  The target to listen for events on

  Parameter event

  The DOM event name

  Parameter handler

  An event handler

  Parameter capture

  Whether or not to listen during the capture event phase

function useGlobalListener

useGlobalListener: <K extends keyof DocumentEventMap>(
    event: K,
    handler: DocumentEventHandler<K>,
    capture?: boolean | AddEventListenerOptions
) => void;

• Attaches an event handler outside directly to the document, bypassing the react synthetic event system.

  useGlobalListener('keydown', (event) => {
   console.log(event.key)
  })

  Parameter event

  The DOM event name

  Parameter handler

  An event handler

  Parameter capture

  Whether or not to listen during the capture event phase

function useImage

useImage: (
    imageOrUrl?: string | HTMLImageElement | null | undefined,
    crossOrigin?: 'anonymous' | 'use-credentials' | string
) => State;

• Fetch and load an image for programatic use such as in a <canvas> element.

  Parameter imageOrUrl

  The HtmlImageElement or image url to load

  Parameter crossOrigin

  The crossorigin attribute to set

  const { image, error } = useImage('/static/kittens.png')
  const ref = useRef<HTMLCanvasElement>()
  
  useEffect(() => {
    const ctx = ref.current.getContext('2d')
  
    if (image) {
      ctx.drawImage(image, 0, 0)
    }
  }, [ref, image])
  
  return (
    <>
      {error && "there was a problem loading the image"}
      <canvas ref={ref} />
    </>

function useInterval

useInterval: {
    (fn: () => void, ms: number): void;
    (fn: () => void, ms: number, paused: boolean): void;
    (fn: () => void, ms: number, paused: boolean, runImmediately: boolean): void;
};

• Creates a setInterval that is properly cleaned up when a component unmounted

   function Timer() {
     const [timer, setTimer] = useState(0)
     useInterval(() => setTimer(i => i + 1), 1000)
  
     return <span>{timer} seconds past</span>
   }

  Parameter fn

  an function run on each interval

  Parameter ms

  The milliseconds duration of the interval

• Creates a pausable setInterval that is properly cleaned up when a component unmounted

   const [paused, setPaused] = useState(false)
   const [timer, setTimer] = useState(0)
  
   useInterval(() => setTimer(i => i + 1), 1000, paused)
  
   return (
     <span>
       {timer} seconds past
  
       <button onClick={() => setPaused(p => !p)}>{paused ? 'Play' : 'Pause' }</button>
     </span>
  )

  Parameter fn

  an function run on each interval

  Parameter ms

  The milliseconds duration of the interval

  Parameter paused

  Whether or not the interval is currently running

• Creates a pausable setInterval that _fires_ immediately and is properly cleaned up when a component unmounted

   const [timer, setTimer] = useState(-1)
   useInterval(() => setTimer(i => i + 1), 1000, false, true)
  
   // will update to 0 on the first effect
   return <span>{timer} seconds past</span>

  Parameter fn

  an function run on each interval

  Parameter ms

  The milliseconds duration of the interval

  Parameter paused

  Whether or not the interval is currently running

  Parameter runImmediately

  Whether to run the function immediately on mount or unpause rather than waiting for the first interval to elapse

function useMergeState

useMergeState: <TState extends {}>(
    initialState: TState | (() => TState)
) => [TState, MergeStateSetter<TState>];

• Mimics a React class component's state model, of having a single unified state object and an updater that merges updates into the existing state, as opposed to replacing it.

  const [state, setState] = useMergeState({ name: 'Betsy', age: 24 })
  
  setState({ name: 'Johan' }) // { name: 'Johan', age: 24 }
  
  setState(state => ({ age: state.age + 10 })) // { name: 'Johan', age: 34 }

  Parameter initialState

  The initial state object

function useMergeStateFromProps

useMergeStateFromProps: <TProps, TState extends {}>(
    props: TProps,
    gDSFP: Mapper<TProps, TState>,
    initialState: TState
) => [TState, MergeStateSetter<TState>];

function useMounted

useMounted: () => () => boolean;

• Track whether a component is current mounted. Generally less preferable than properlly canceling effects so they don't run after a component is unmounted, but helpful in cases where that isn't feasible, such as a Promise resolution.

  Returns

  a function that returns the current isMounted state of the component

  const [data, setData] = useState(null)
  const isMounted = useMounted()
  
  useEffect(() => {
    fetchdata().then((newData) => {
       if (isMounted()) {
         setData(newData);
       }
    })
  })

function usePrevious

usePrevious: <T>(value: T) => T | null;

• Store the last of some value. Tracked via a Ref only updating it after the component renders.

  Helpful if you need to compare a prop value to it's previous value during render.

  function Component(props) {
    const lastProps = usePrevious(props)
  
    if (lastProps.foo !== props.foo)
      resetValueFromProps(props.foo)
  }

  Parameter value

  the value to track

function useRafInterval

useRafInterval: (fn: () => void, ms: number) => void;

function useResizeObserver

useResizeObserver: <TElement extends Element>(
    element: TElement | null | undefined
) => Rect | null;

• Efficiently observe size changes on an element. Depends on the ResizeObserver api, and polyfills are needed in older browsers.

  const [ref, attachRef] = useCallbackRef(null);
  
  const rect = useResizeObserver(ref);
  
  return (
   <div ref={attachRef}>
     {JSON.stringify(rect)}
   </div>
  )

  Parameter element

  The DOM element to observe