useSearchParams

The useSearchParams hook simplifies modifying the URL search parameters. It provides functions to get, set, append, and delete search parameters.

Overview

This hook can be used in two main forms:

1. Without a specific key: In this case, each of the functions needs to be provided with a search parameter key that should be modified.
2. With a specific key: In this case, you only need to pass the key when calling the hook. Calls to each of the functions do not need to be provided with the key. The first value returned by the hook will be the value of the parameter.

Configuration

The hook accepts an optional configuration object as its second parameter:

type UseSearchParamsConfig = {
    getAll?: boolean;
    fallbackValue?: boolean;
};

• getAll: When set to true, the hook will return all values for a given key instead of just the first one.
• fallbackValue: When set, the hook will return this value instead of undefined.

Usage

Keyless Mode

When used without a key, useSearchParams returns an array containing functions that manage all search parameters.

import { useSearchParams } from '@archibald/core';

import { useState, FC } from 'react';

const TestKeylessSearchParams: FC = () => {
    const [key, setKey] = useState<string>('');
    const [value, setValue] = useState<string>('');
    const [output, setOutput] = useState<string>('');

    const [getParam, { set: setParam, append: appendParam, delete: deleteParam }] = useSearchParams();

    const handleSet = () => {
        setParam({ [key]: value });
        setOutput(`Set ${key} = ${value}`);
    };

    const handleAppend = () => {
        appendParam(key, value);
        setOutput(`Appended ${key} = ${value}`);
    };

    const handleDelete = () => {
        deleteParam(key);
        setOutput(`Deleted ${key}`);
    };

    const handleGet = () => {
        const result = getParam(key);
        setOutput(`Value of ${key}: ${result}`);
    };

    return (
        <div>
            <input type="text" placeholder="Key" value={key} onChange={(e) => setKey(e.target.value)} />
            <br />
            <input type="text" placeholder="Value" value={value} onChange={(e) => setValue(e.target.value)} />
            <div>
                <button onClick={handleSet}>Set Param</button>
                <br />
                <button onClick={handleAppend}>Append Param</button>
                <br />
                <button onClick={handleDelete}>Delete Param</button>
                <br />
                <button onClick={handleGet}>Get Param</button>
            </div>
            <p>Output: {output}</p>
        </div>
    );
};

Keyed Mode

When a specific key is provided, useSearchParams manages only that parameter. It returns the current value of the parameter, along with the functions to set, append, delete, and get the parameter.

import { useSearchParams } from '@archibald/core';

import { useState, FC } from 'react';

export const TestKeyedSearchParams: FC = () => {
    const key = 'defaultKey';
    const [value, setValue] = useState<string>('');
    const [output, setOutput] = useState<string>('');

    const [param, { set: setParam, append: appendParam, delete: deleteParam }] = useSearchParams(key, { getAll: true });

    const handleSet = () => {
        setWithKey(value);
        setOutput(`Set ${key} = ${value}`);
    };

    const handleAppend = () => {
        appendWithKey(value);
        setOutput(`Appended to ${key}: ${value}`);
    };

    const handleDelete = () => {
        deleteWithKey();
        setOutput(`Deleted parameter ${key}`);
    };

    const handleGet = () => {
        const result = getWithKey();
        setOutput(`Current value(s) of ${key}: ${result}`);
    };

    return (
        <div>
            <input type="text" placeholder="Value" value={value} onChange={(e) => setValue(e.target.value)} />
            <br />
            <div>
                <button onClick={handleSet}>Set Param</button>
                <br />
                <button onClick={handleAppend}>Append Param</button>
                <br />
                <button onClick={handleDelete}>Delete Param</button>
                <br />
                <button onClick={handleGet}>Get Param</button>
            </div>
            <p>
                Current value(s) of {key}: {Array.isArray(param) ? param.join(', ') : param}
            </p>
            <p>Output: {output}</p>
        </div>
    );
};