readme.md

unihooks

Essential hooks collection for everyday react¹ projects.

Principles

1. Framework agnostic

Unihooks are not bound to react and work with any hooks-enabled framework:

• react
• preact
• haunted
• neverland
• atomico
• fuco
• spect
• augmentor

See any-hooks for the full list.

2. Unified

Unihooks follow useState signature for intuitivity.

let [ state, actions ] = useValue( target?, init | update? )

3. Essential

Unihooks deliver value in reactive context, they're not mere wrappers for native API. Static hooks are avoided.

const MyComponent = () => { let ua = useUserAgent() } // ✘ − user agent never changes
const MyComponent = () => { let ua = navigator.userAgent } // ✔ − direct API must be used instead

Hooks

useChannel

[value, setValue] = useChannel(key, init?, deps?)

Global value provider - useState with value identified globally by key. Can be used as value store, eg. as application model layer without persistency. Also can be used for intercomponent communication.

init can be a value or a function, and (re)applies if the key (or deps) changes.

import { useChannel } from 'unihooks'

function Component () {
  let [users, setUsers] = useChannel('users', {
    data: [],
    loading: false,
    current: null
  })

  setUsers({ ...users, loading: true })

  // or as reducer
  setUsers(users => { ...users, loading: false })
}

useStorage

[value, setValue] = useStorage(key, init?, options?)

useChannel with persistency to local/session storage. Subscribes to storage event - updates if storage is changed from another tab.

import { useStorage } from 'unihooks'

function Component1 () {
  const [count, setCount] = useStorage('my-count', 1)
}

function Component2 () {
  const [count, setCount] = useStorage('my-count')
  // count === 1

  setCount(2)
  // (↑ updates Component1 too)
}

function Component3 () {
  const [count, setCount] = useStorage('another-count', (value) => {
    // ...initialize value from store
    return value
  })
}

options

• prefix - prefix that's added to stored keys.
• storage - manually pass session/local/etc storage.

Reference: useStore.

useAction

[action] = useAction(key, cb, deps?)

Similar to useChannel, but used for storing functions. Different from useChannel in the same way the useCallback is different from useMemo. deps indicate if value must be reinitialized.

function RootComponent() {
  useAction('load-content', async (slug, fresh = false) => {
    const url = `/content/${slug}`
    const cache = fresh ? 'reload' : 'force-cache'
    const res = await fetch(url, { cache })
    return await res.text()
  })
}

function Content ({ slug = '/' }) {
  let [content, setContent] = useState()
  let [load] = useAction('load-content')
  useEffect(() => load().then(setContent), [slug])
  return html`
    <article>${content}</article>
  `
}

useSearchParam

[value, setValue] = useSearchParam(name, init?)

Reflect value to location.search. value is turned to string via URLSearchParams. To serialize objects or arrays, provide .toString method or convert manually.

NOTE. Patches history.push and history.replace to enable pushstate and replacestate events.

function MyComponent () {
  let [id, setId] = useSearchParam('id')
}

useCountdown

[n, reset] = useCountdown(startValue, interval=1000 | schedule?)

Countdown value from startValue down to 0 with indicated interval in ms. Alternatively, a scheduler function can be passed as schedule argument, that can be eg. worker-timers-based implementation.

import { useCountdown } from 'unihooks'
import { setInterval, clearInterval } from 'worker-timers'

const Demo = () => {
  const [count, reset] = useCountdown(30, fn => {
    let id = setInterval(fn, 1000)
    return () => clearInterval(id)
  });

  return `Remains: ${count}s`
};

useValidate

[error, validate] = useValidate(validator: Function | Array, init? )

Provides validation functionality.

• validator is a function or an array of functions value => error | true ?.
• init is optional initial value to validate.

function MyComponent () {
  let [usernameError, validateUsername] = useValidate([
    value => !value ? 'Username is required' : true,
    value => value.length < 2 ? 'Username must be at least 2 chars long' : true
  ])

  return <>
    <input onChange={e => validateUsername(e.target.value) && handleInputChange(e) } {...inputProps}/>
    { usernameError }
  </>
}

useFormField

[props, field] = useFormField( options )

Form field state controller. Handles input state and validation. Useful for organizing controlled inputs or forms, a nice minimal replacement to form hooks libraries.

let [props, field] = useFormField({
  name: 'password',
  type: 'password',
  validate: value => !!value
})

// to set new input value
useEffect(() => field.set(newValue))

return <input {...props} />

options

• value - initial input value.
• persist = false - persist input state between sessions.
• validate - custom validator for input, modifies field.error. See useValidate.
• required - if value must not be empty.
• ...props - the rest of props is passed to props

field

• value - current input value.
• error - current validation error. Revalidates on blur, null on focus.
• valid: bool - is valid value, revalidates on blur.
• focus: bool - if input is focused.
• touched: bool - if input was focused.
• set(value) - set input value.
• reset() - reset form state to initial.
• validate(value) - force-validate input.

useInput

[value, setValue] = useInput( element | ref )

Uncontrolled input element hook. Updates if input value changes. Setting null / undefined removes attribute from element. Useful for organizing simple input controllers, for advanced cases see useFormField.

function MyButton() {
  let ref = useRef()
  let [value, setValue] = useInput(ref)

  useEffect(() => {
    // side-effect when value changes
  }, [value])

  return <input ref={ref} />
}

useObservable

[state, setState] = useObservable(observable)

Observable as hook. Plug in any spect/v, observable, mutant, observ be free.

import { v } from 'spect/v'

const vCount = v(0)

function MyComponent () {
  let [count, setCount] = useObservable(vCount)

  useEffect(() => {
    let id = setInterval(() => setCount(count++), 1000)
    return () => clearInterval(id)
  }, [])

  return <>Count: { count }</>
}

standard

For convenience, unihooks export current framework hooks. To switch hooks, use setHooks - the default export.

import setHooks, { useState, useEffect } from 'unihooks'
import * as hooks from 'preact/hooks'

setHooks(hooks)

function Timer() {
  let [count, setCount] = useState(0)
  useEffect(() => {
    let id = setInterval(() => setCount(c => ++c))
    return () => clearInterval(id)
  }, [])
}

utility

Utility hooks, useful for high-order-hooks.

update = useUpdate()

Force-update component, regardless of internal state.

prev = usePrevious(value)

Returns the previous state as described in the React hooks FAQ.

See also

• any-hooks - cross-framework standard hooks provider.
• enhook - run hooks in regular functions.

Alternatives

• valtio

License

MIT

HK