@react-params/core

@react-params

Monorepo for @react-params - Opinionated url state (search params) React library

---

Rationale | Sample Usage | Installation | Setup | Advanced use cases | API

---

Rationale

There are multiple issues with native URL state management in React:

• its not strongly typed
• managing state update is tricky (causing unnecessary re-renders)
• no unified hook api for common use cases like:
  • default values
  • prefixing
  • validation

This library is solving those by:

• Using Typescript
• Optimizing the rendering process
  • special useSet method for only updating search param
  • don't re-render on every url change (compares values internally and only updates if changed)
• Using single interface across multiple frameworks (react-router-dom, remix, vanilla)
• Providing multiple utilities:
  • batching support
  • working both SSR and client side
  • parameter prefixes options
  • built in method for generating urls
  • grouping of params
  • support replace and push state methods
  • custom serialization
  • validation
  • custom setters (e.g. bool toggle method, or dialog open)

Simple Usage

import {create} from "@react-params/core";

const params = create({
    "user-name": f.string(),
    //number and  types are supported
    "counter": f.number().withDefault(0),
    //for object we specify type
    "address": f.object<{ a: string }>(),
    //list of strings
    "colors": f.list({separator: ",", item: f.string()}).withDefault([]),
});

const Component = () => {
    // all params are auto mapped from kebab case to camel case
    //react useState like hook result (setter supports dispatch shape: value or (prev)=> newValue)
    const [value, setValue] = params.userName.use();
    
    //useSet result in not subscribing to this param changes resulting in optimized renders
    const setAddress = params.address.useSet();

    //you can overrride default param settings in particular default value
    const [colors, setColors] = params.list.use({
        defaultValue: ["green", "red"],
        prefix: "prefix"
    });

    return <div/>
};

Installation

Depending on project setup:

• vanilla react npm install @react-params/core
• react-router-dom npm install @react-params/react-router-dom
• remix npm install @react-params/remix
• react-router (v7) npm install @react-params/react-router

Setup

For vanilla react no additional setup is required.
For framework adapters:

• @react-params/react-router-dom
• @react-params/remix
• @react-params/react-router

You need to wrap your app with <ReactParamsApiProvider/> component provided by each of package.

import {ReactParamsApiProvider} from "@react-params/react-router-dom";

const App = () => {
    return (
        <ReactParamsApiProvider>
          <div />
        </ReactParamsApiProvider>
    )
}

Checkout those sandboxes for fully working examples:

• vanilla react
• react-router-dom
• react-router
• remix

Note

• You can import factory functions createand p from @react-params/core package or adapter package used for your framework.

import {create} from "@react-params/core";
//or 
import {create} from "@react-params/react-router";
//or
import {create} from "@react-params/react-router-dom";

Advanced use cases

• links generation link
• single param usage (without grouping) link
• batching support link
• transforming the shape of useSet method link
• transforming the shape of useSet method to support table pagination link

API

create

Creates a new params instance. Accepts a schema object where each key is a param name and value is a param builder. Returns an instance of ReactParams`

import {create} from "@react-params/core";

const params = create({
    "param-name": paramBuilder, //e.g. p.string()
    ...
});

ReactParams

(ReturnType<type of create>)

Represents the params instance. For each param defnied there is camelCase substitute with two methods:

• use returns a tuple of [value, setValue]
• useSet returns a set method

const [value, setValue] = params.paramName.use();
const setParamName = params.paramName.useSet();

Besides this ReactParams provide:

• batch method
• withOptions method (add ability to provide global options)
• build - utility method to build url params (to be used in links generation)

p

A function that creates a new param builder. Possible methods are:
string, number, boolean, datetime, date, object

Each of those method accepts options (currently updateType which specifies how the param should be updated in the url)

updateType

Name	Description
replaceIn (default)	Replaces the current url with the new one
pushIn	Pushes the new url to the current url
replace	Replaces the current url with the new one, but doesn't push the new url to the history
push	Pushes the new url to the history

All builders have following methods:

• withDefault - sets a default value for the param, marking it as non nullable
• validate - sets a custom validator for the param
• withCustomSetter - transforms the param setter result (useful for e.g. toggling a boolean value)
• withSerializer - sets a custom serializer for the param

Example:

import {p} from "@react-params/core";

p.string({updateType: "replace"}).withDefault("")

Options

you can specify options:

• globally (by calling withOptions method on ReactParams instance)
• per param (by passing those to use and useSet methods)

options

Name	Description
updateType	Sets the update type for the param.
defaultValue	Sets a default value for the param, marking it as non nullable
prefix	Sets prefix to be used with param name