Redux Callback Router
This is the Redux flavor of Callback Router, which allows you to keep the URL synchronized with your Redux state In addition to generic callbacks, you can map routes to action creators so that navigation will dispatch an action.
Install
yarn:
yarn add redux-callback-router
npm:
npm install redux-callback-router
Usage
; ; // Map the state to paths { if stateid if actiontype === 'CHANGE_USER' // Return a string for the pushState destination return `/users/`; else // Return [string, options] to customize navigation return `/users/` replaceState: true ; // Otherwise, leave path unchanged return null;} // Wrap the router to update the path on state changesconst reducer = ; // Use the wrapped reducer to create your Redux storeconst store = ; // Register the routesconst unregisterRoutes evaluate = ; // Evaluate the current URI; // Unregister the routes;
API
registerRoutes(routes, callback)
evaluate(pathname, state, type, routes)
navigate(path, options)
createCallbackRouterReducer(reducer, mapStateToPath, navigateInitialState)
registerRoutes
Registers paths to their callbacks.
Returns functions to unregister the routes and evaluate a given path.
const unregisterRoutes evaluate = ;
Returns { unregisterRoutes, evaluate }
.
routes
(Object
)
Map of paths to route definitions, actions creators, or actions.
The path may contain named :params
or (.*)
wildcards.
Route definitions have the following properties:
action
(Object
)
A Redux action that is dispatched when the route is matched.
action(params, type, pathname, state, path, getState)
Function that generates an action to be dispatched when the route is matched.
callback(params, type, dispatch, getState, pathname, state, path)
Function invoked when the route is matched.
This is an alternative to action
for cases where a route needs to dispatch
multiple actions or have some other special behavior.
exact
(boolean
, defaults to false
)
When set, this will not honor a partial match.
For example a URI /user/123
would not match the route /user
.
last
(boolean
, defaults to true
)
When set, a match on this route will prevent subsequent lower-priority routes from being evaluated.
navigate
(boolean
, defaults to false
)
When set, this route will be evaluated for imperative navigation (pushState
and replaceState
) whether or not navigation is forced.
strict
(boolean
, defaults to false
)
When set, the trailing slash must be present or omitted exactly as the route is
defined. For example, a URI /users
would not match the route /users/
, or
vise-versa.
callback(result)
(Function
, optional)
Common callback invoked at the end of any matching route's callback.
evaluate
Determines which routes match the pathname and invokes their callbacks.
Returns the value returned from the callback of the highest-priority (first) matching route.
const result = ;
pathname
(string
, defaults to document.location.pathname
)
URI to evaluate
state
(Object
, defaults to window.history.state)
Additional state data associated with the current history item.
type
(string
)
Navigation type used to differentiate between imperative navigation and browser navigation.
ROUTE_CHANGE_INITIALIZE
: Router was first registeredROUTE_CHANGE_PUSH_STATE
: Imperative navigation (skips callback)ROUTE_CHANGE_REPLACE_STATE
: Imperative navigation (skips callback)ROUTE_CHANGE_POP_STATE
: Browser navigation (invokes callback)ROUTE_CHANGE_FORCE_PUSH_STATE
: Imperative navigation (invokes callback)ROUTE_CHANGE_FORCE_REPLACE_STATE
: Imperative navigation (invokes callback)ROUTE_CHANGE_UNKNOWN
: Unknown navigation type
routes
(Object
, defaults to all registered routes)
Map of paths to route definitions or callbacks.
navigate
Performs imperative navigation.
By default, this only modifies history using pushState
or replaceState
.
Routes without navigate
enabled are not evaluated unless the force
option
is enabled!
Returns the result of the callback if a route was evaluated.
const result = ;
path
(string
)
Destination pathname.
options.force
(boolean
, defaults to false
)
When set, this will evaluate non-navigate
routes.
options.replaceState
(boolean
, defaults to false
)
When set, this replaces the current history state instead of pushing an additional state.
options.state
(Object
, defaults to {}
)
Additional data associated with the state.
options.title
(string
, defaults to document.title
)
Title of the history state.
createCallbackRouterReducer
Creates a wrapped reducer that can update the history based on the state.
const wrappedReducer = ;
reducer
(Function
)
Reducer to connect to the Callback Router.
mapStateToPath(state, action, prevState)
Function that determines the URL from the state (and/or action).
The return value is used to determine whether and how navigate
is invoked.
Return a string to push a new history state. Return an array with a string and
an object to specify the navigation options
.
navigateInitialState
(boolean
, defaults to false
)
The initial reducer call doesn't represent a state change, so navigation doesn't typically make sense. Setting this will ignore that and attempt to navigate after the initial reducer invocation.
License
ISC © Keith McKnight