manage query parameters with react-hooks
npm install geschichte🇺🇦 Support Ukraine 🇺🇦 Help Provide Humanitarian Aid to Ukraine.
!CircleCI
!Codecov
!npm

Geschichte (german for History / Story / Tale) Let's you manage query-parameters with hooks.
Uses immer and zustand to manage the internal state.
Documentation & Demo: https://bowlingx.github.io/geschichte/index.html
API: https://bowlingx.github.io/geschichte/api/index.html
yarn add geschichte
npm install geschichte
``typescript jsx
import { pm, factoryParameters, serializers } from 'geschichte'
import { GeschichteWithHistory } from 'geschichte/historyjs'
import { createBrowserHistory } from 'history'
const parameterConfig = {
item: pm(
'queryParameter',
serializers.string /* a basic collection of serializers is availble, like date, int, float, arrays /,
(value?: V, initialValue?: V) =>
boolean /* define an optional skip function which will determine if the parameter will be included in the url or not /
),
/ ... more keys, any depth. /
}
// default value is either an object or a factory () => defaultValue
const defaultValue = {
item: 'defaultValue' /* it automatically skips null or default values/,
}
// exports a hook (useQuery), andcreateQueryString
// utility methods that let's you create a query string based on the described object anywhere outside of components etc.parseQueryString
// let's you parse a query string into an object as defined in the parameterConfig.
const { useQuery, createQueryString, parseQueryString } = factoryParameters(
parameterConfig,
defaultValue /* optional namespace, (creates a prefix separated by a dot)/
)
const Component = () => {
const {
values,
pushState,
replaceState,
resetPush,
resetReplace,
createQueryString,
batchReplaceState,
batchPushState,
} = useQuery()
return (
<>
onClick={() => pushState((values) => void (values.item = 'newValue'))}
>
push new state
onClick={() =>
replaceState((values) => void (values.item = 'anotherOne'))
}
>
replace state
const App = () => (
)
`
Geschichte let's you describe and serialize an arbitrary object of any depth to your browsers query and history.immerjs
It takes care of updating the next state and current query in a efficient way using .createMemoryHistory
It works on both the browser and server side (with )
I was inspired by immer and zustand, so I picked a fitting german name :).
- Add more tests
- Propper examples and documentation of the full API
- Describe Use-Cases
It works out of the box with react-router (by providing the same history instance).
Nextjs support is build in, but requires a different Adapter.
#### With page router
`tsx
/* _app.tsx /
import React, { memo } from 'react'
import GeschichteForNextjs from 'geschichte/nextjs'
import type { AppProps } from 'next/app'
function App({ Component, pageProps }: AppProps) {
return (
)
}
export default memo(App)
`
#### With App router
You can use Geschichte with the app router as well (from nextjs 13).
`tsx
/* page.tsx /
import Geschichte from 'geschichte/nextjs-app-router'
import MoreComponentsWithClientSideState from '@/components/ClientComponents'
export default function Home() {
return (
)
}
``