tanbal-hooks

A collection of useful and reusable React and Next.js hooks.

Installation

npm install tanbal-hooks

Hooks

• useDataManager
• useLocalStorage
• useClickOutside
• useInputBlur
• useQueryParams

useDataManager

A hook for managing data through REST API requests.

Usage

import useDataManager from 'tanbal-hooks';

const [data, status, actions] = useDataManager('/api/users');

Return value

[data, status, actions]

status can be:

idle
loading
loaded
failed

actions contains:

{
    load,
    add,
    update,
    updateMultiple,
    remove,
    get,
}

Methods

load(successCallback, failCallback, finallyCallback)

Loads data using GET.

await actions.load(
    data => console.log(data),
    error => console.error(error),
    () => console.log('finished')
);

add(data, successCallback, failCallback, finallyCallback)

Adds a new item using POST.

await actions.add({
    name: 'Ali',
});

update(id, newData, successCallback, failCallback, finallyCallback)

Updates an item using PATCH.

await actions.update(1, {
    name: 'Ali Reza',
});

updateMultiple(updates, successCallback, failCallback, finallyCallback)

Updates multiple items using PATCH.

await actions.updateMultiple([
    { id: 1, name: 'Ali' },
    { id: 2, name: 'Reza' },
]);

remove(id, successCallback, failCallback, finallyCallback)

Removes an item using DELETE.

await actions.remove(1);

get(which, key = 'id')

Finds an item by a specified key.

const user = actions.get(1);

const user = actions.get('Ali', 'name');

useLocalStorage

A hook for storing and synchronizing a value with localStorage.

Usage

import useLocalStorage from 'tanbal-react-hooks';

const [value, setValue] = useLocalStorage('theme', 'light');

The hook returns:

[value, setValue]

The stored value is automatically read from localStorage when the key changes and saved whenever the value changes.

useClickOutside

A hook for detecting clicks outside of an element.

Usage

import useClickOutside from 'tanbal-react-hooks';

const ref = useClickOutside(() => {
    console.log('Clicked outside');
}, true);

return (
    <div ref={ref}>
        Content
    </div>
);

Parameters

useClickOutside(onOutsideClick, isActive)

• onOutsideClick — callback called when a click occurs outside the referenced element.
• isActive — enables or disables the listener. Defaults to false.

useInputBlur

A hook for handling input events with a delay and executing a callback when the input loses focus.

Usage

import useInputBlur from 'tanbal-react-hooks';

const inputRef = useInputBlur(500, value => {
    console.log(value);
});

return <input ref={inputRef} />;

Parameters

useInputBlur(time, callback)

• time — delay in milliseconds before the callback is executed after input.
• callback — callback receiving the current input value.

The callback is also executed immediately when the input loses focus.

useQueryParams

A Next.js hook for managing URL query parameters and synchronizing them with React state.

This hook uses next/navigation and is intended for Next.js App Router applications.

Usage

import useQueryParams from 'tanbal-react-hooks';

const [query, state, setState] = useQueryParams(
    {
        search: '',
    },
    {
        search: {
            path: 'search',
        },
    }
);

The hook returns:

[actions, state, setState]

Actions

{
    get,
    set,
    setMultiple,
    remove,
    removeParams,
    reset,
    getPath,
}

get(key)

Gets a query parameter.

const value = query.get('search');

Returns null when the parameter is empty or does not exist.

set(key, value, replace = true)

Sets a query parameter and updates the corresponding state value.

query.set('search', 'react');

setMultiple(newValues)

Sets multiple query parameters at once.

query.setMultiple({
    search: 'react',
    page: 2,
});

remove(key, replace = true)

Removes a query parameter and clears its corresponding state value.

query.remove('search');

removeParams(paramsList)

Removes multiple query parameters.

query.removeParams(['search', 'page']);

reset()

Removes all configured query parameters.

query.reset();

getPath(key)

Returns the configured state path for a query parameter.

const path = query.getPath('search');

Configuration

Each query parameter can be configured with:

{
    search: {
        path: 'filters.search',
        emptyValues: [''],
        inputTransform: value => value,
        paramsTransform: value => value,
    },
}

• path — path used to store the parameter in the state.
• emptyValues — values treated as empty.
• inputTransform — transforms values before storing them in the state or URL.
• paramsTransform — transforms values read from the URL before storing them in the state.

Options

The third argument can be used to configure initial parameter synchronization:

useQueryParams(initialState, keys, {
    syncInitialParams: true,
});

syncInitialParams defaults to true.

License

MIT