https://github.com/dean177/use-url-state

Lift a React component's state into the url
https://github.com/dean177/use-url-state

higher-order-component hooks javascript react render-props state-management typescript

Last synced: 4 days ago
JSON representation

Lift a React component's state into the url

• Host: GitHub
• URL: https://github.com/dean177/use-url-state
• Owner: Dean177
• License: mit
• Created: 2017-07-29T17:28:15.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2022-12-10T01:32:37.000Z (about 2 years ago)
• Last Synced: 2025-01-07T09:19:10.524Z (11 days ago)
• Topics: higher-order-component, hooks, javascript, react, render-props, state-management, typescript
• Language: TypeScript
• Homepage:
• Size: 8.94 MB
• Stars: 154
• Watchers: 4
• Forks: 13
• Open Issues: 30
• Metadata Files:
  • Readme: Readme.md
  • Changelog: CHANGELOG.md
  • License: License

Awesome Lists containing this project

README

        
# with-url-state

[![CircleCI](https://circleci.com/gh/Dean177/with-url-state.svg?style=shield)](https://circleci.com/gh/Dean177/with-url-state)

[![codecov](https://codecov.io/gh/Dean177/with-url-state/branch/master/graph/badge.svg)](https://codecov.io/gh/Dean177/with-url-state)

[![Npm](https://badge.fury.io/js/with-url-state.svg)](https://www.npmjs.com/package/with-url-state)

Lifts the state out of a react component and into the url

![color-example](./demo/color-example.gif)

## Hooks

There is a [hook](https://reactjs.org/docs/hooks-intro.html) based api available on the [3.0.0](https://github.com/Dean177/with-url-state/tree/3.0.0) branch, published as a beta on [npm](https://www.npmjs.com/package/with-url-state/v/3.0.0-beta.0).

## Installation

To install with npm use

`npm install with-url-state --save`

To install with yarn use

`yarn add with-url-state`

## Usage

Check out the the [demo](https://dean177.github.io/with-url-state/) view the [code](https://github.com/Dean177/with-url-state/tree/master/demo) or play with it in [CodeSandbox](https://codesandbox.io/s/18x4l87yx7). 

Using javascript

```javascript

import React from 'react'

import { withUrlState } from 'with-url-state'

const enhance = withUrlState(props => ({ color: 'blue' }))

export const UrlForm = enhance(props => (

  


    


      
{props.urlState.color}

    

    


       props.setUrlState({ color: 'red' })}>

        Red

      

       props.setUrlState({ color: 'green' })}>

        Green

      

       props.setUrlState({ color: 'blue' })}>

        Blue

      

    

  

))

```


Using typescript

```typescript jsx

import React from 'react'

import { withUrlState, UrlStateProps } from 'with-url-state'

type OwnProps = {}

type UrlState = { color: string }

const enhance = withUrlState((prop: OwnProps) => ({ color: 'blue' }))

export const UrlForm = enhance((props: OwnProps & UrlStateProps) => (

  


    


      
{props.urlState.color}

    

    


       props.setUrlState({ color: 'red' })}>

        Red

      

       props.setUrlState({ color: 'green' })}>

        Green

      

       props.setUrlState({ color: 'blue' })}>

        Blue

      

    

  

))

```


Using the render-prop component

```typescript jsx

import React from 'react'

import { UrlState } from 'with-url-state'

type OwnProps = {}

type UrlState = { color: string }

export const UrlForm = (props: OwnProps) => (

   (

      


        


          
{urlState.color}

        

        


           setUrlState({ color: 'red' })}>

            Red

          

           setUrlState({ color: 'green' })}>

            Green

          

           setUrlState({ color: 'blue' })}>

            Blue

          

        

      

    )}

  />

)

```


## Motivation

`with-url-state` automates the query parameter manipulations, simplifying URL sharing for search results, querying data or tracking a visible portion of a map.

The api provided is:

- based on [higer-order-components](https://reactjs.org/docs/higher-order-components.html) which makes it composable and testable

- has a render-prop alternative for convenience

- type-safe thanks to [Typescript](https://www.typescriptlang.org/)

- very similar to [Reacts built in state](https://reactjs.org/docs/state-and-lifecycle.html) apis, so converting a component which already manages state is usually as simple as replacing `setState` with `setUrlState`!

## Pollyfill

For use in IE11 you will need [https://github.com/kumarharsh/custom-event-polyfill](https://github.com/kumarharsh/custom-event-polyfill)

and add `import 'custom-event-polyfill';` 

`if (typeof Event !== 'function') { window.Event = CustomEvent; }` to the upper scope of your application.