Skip to content

woltapp/react-router-query-params

Repository files navigation

react-router-query-params

npm version Download Count

Set query parameters with a schema for react-router.

Install

npm install --save react-router-query-params

Peer dependencies

  • react
  • react-router v. ^4.0.0 or ^5.0.0
  • react-router-dom v. ^4.0.0 or ^5.0.0

Example

import withQueryParams from 'react-router-query-params';
...

const ExampleComponent = ({
  queryParams,
  setQueryParams,
}) = (
  <div>
    <div>
      queryParams: {JSON.stringify(queryParams)}
    </div>

    <button onClick={() => setQueryParams({ example1: 'someQueryParam' })}>
      Set query param example
    </button>
  </div>
);

const ConnectedComponent = withQueryParams({
  stripUnknownKeys: false,
  keys: {
    example1: {
      default: 'example-1-default',
      validate: value => !!value && value.length > 3,
    },
    example2: {
      default: (value, props) => props.defaultValue,
      validate: (value, props) =>
        !!value && !props.disallowedValues.includes(value)
    }
  }
})(ExampleComponent);

API

Props

  • queryParams (object): All current query parameters as key-value pairs in an object.

  • setQueryParams (function): Set one or more query parameters.

this.props.setQueryParam({ key1: 'value1', key2: 'value2' })

HoC

The library exports withQueryParams higher order component as default. The HoC takes a configuration object as the first argument, and has the following options:

  • stripUnknownKeys (boolean)

    • if true, removes keys from query parameters that are not configured with keys
    • default: false
  • keys (object)

    • example:
      keys: {
        example: {
          default: 'default-value',
          validate: () => true
        }
      }

Key configuration object

Key object is used to create a configuration for the query parameters that are intended to be used. Every key is configured with the following properties:

  • default (any): Define the default value for the query parameter. If query parameter valiation fails or it is undefined, the HoC automatically sets the query parameter to this value. Examples:

    • default: 'example': sets 'example' as default value
    • default: (value, props) => props.defaultParam': sets defaultParam from the component props as default value
    • default: undefined: do not set query parameter at all by default
  • validate (function): Validate the query parameter and revert to default value if validation does not pass. Examples:

    • validate: () => true: allow any alue
    • validate: value => !!value && value.length > 2: allow any value with more than two characters
    • validate: (value, props) => props.allowedValues.includes(values): validate value based on props

License

MIT