npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@ptolemy2002/react-search-param-state

v3.0.1

Published

This library works with `react-router-dom` to provide a hook that allows you to store and retrieve state in the URL search parameters, allowing users to share links with the state included and to refresh the page without losing the state.

Downloads

330

Readme

React Search Param State

This library works with react-router-dom to provide a hook that allows you to store and retrieve state in the URL search parameters, allowing users to share links with the state included and to refresh the page without losing the state.

The hook is exported as default, so you can import in one of the following ways:

// ES6
import useSearchParamState from '@ptolemy2002/react-search-param-state';
// CommonJS
const useSearchParamState = require('@ptolemy2002/react-search-param-state');

Type Reference

type SetSearchParamAction<T extends Record<string, any>, K extends keyof T> = MaybeTransformer<T[K], [T[K]]>;
type SetSearchParamFunction<T extends Record<string, any>> = (
    values: MaybeTransformer<
        MaybeTransformerRecord<SetSearchParamAction<T, keyof T>>,
        [TAndOthers<T>]
        >
    ) => void
;

type ConvertFunctions<T extends Record<string, any>> = {
    [K in KeysNotMatchingEqualTypes<T, string | null>]: (value: string | null) => T[K];
};

type UseSearchParamResult<T extends Record<string, any>> = HookResultData<{
    currentValues: TAndOthers<T>;
    set: SetSearchParamFunction<T>;
}, readonly [TAndOthers<T>, SetSearchParamFunction<T>]>;

Note that the HookResult class comes from the @ptolemy2002/react-hook-result library, a peer dependency of this library. The UseSearchParamResult type combines itself with an array ONLY for the purpose of allowing destructuring to work correctly. Do not attempt to access array properties in UseSearchParamResult directly, as they do not actually exist.

Hooks

The following hooks are available in the library:

useSearchParamState<T extends Record<string, any>>

Description

With your specified defaultVaues, retrieve state from the URL parameters, converting values as specified. The hook will return with a funtion that can be used to update the state. T represents the type of the parameters you expect, though know that the result will include all parameters in the URL, even if they are not part of this type.

Parameters

  • defaultValues (Partial<T>): An object containing the default values for the state. The keys are the names of the state variables, and the values are the default values. The values can be any type, but they will be converted to strings when stored in the URL.
  • converts (ConvertFunctions<T>): An object containing functions to convert the values from strings to the desired type. The keys are the names of the state variables, and the values are functions that take a string and return the desired type. If a key is not present in this object, the value will be used as-is. The type for this requires a convert function to be present for any property that does not have string | null as its value type (EXACTLY) and makes the others optional.

Returns

  • HookResult: A hook result containing the following values in this order:
    • currentValues (TAndOthers<T>): An object containing the current state values, including any default values that were not specified in the URL and any values that were specified in the URL, but not in the default values object.
    • setState (SetSearchParamFunction<T>): A function that can be used to update the state. You can specify a callable as either the parameter itself or one of the values, in both cases the current value of the state/variable will be passed as a parameter to the callable. Any variables that do not appear in the object passed to the function will be left unchanged.

Peer Dependencies

These should be installed in order to use the library, as npm does not automatically add peer dependencies to your project.

  • react: ^18.3.1
  • react-dom: ^18.3.1
  • react-router-dom: ^6.26.2
  • @ptolemy2002/react-hook-result: ^2.1.1
  • @ptolemy2002/js-utils: ^3.0.2

Commands

The following commands exist in the project:

  • npm run uninstall - Uninstalls all dependencies for the library
  • npm run reinstall - Uninstalls and then Reinstalls all dependencies for the library
  • npm run example-uninstall - Uninstalls all dependencies for the example app
  • npm run example-install - Installs all dependencies for the example app
  • npm run example-reinstall - Uninstalls and then Reinstalls all dependencies for the example app
  • npm run example-start - Starts the example app after building the library
  • npm run build - Builds the library
  • npm run release - Publishes the library to npm without changing the version
  • npm run release-patch - Publishes the library to npm with a patch version bump
  • npm run release-minor - Publishes the library to npm with a minor version bump
  • npm run release-major - Publishes the library to npm with a major version bump