react-router-ts
A simple, lightweight react router using hooks, written in TypeScript.
Why use this router?
- Very lightweight (see the badges above for the latest size).
- Flexible and dead simple to use.
- Uses the browsers history API.
- Does not force a matching algorithm on you, but comes with a simple one built-in.
- Written with hooks in TypeScript
- Only has one peer dependency: React 16.12.0 or higher.
- Liberal license: zlib/libpng
Installation via NPM
npm i react-router-ts
This library is shipped as es2015 modules. To use them in browsers, you'll have to transpile them using webpack or similar, which you probably already do.
Examples
Router
You'll need to add a Router
component in your app (just one). Any other components and hooks from this library need to be children of this Router
(doesn't matter how deeply nested).
;;
Route
Showing a component if the location matches a certain path is done with a Route
component. It takes a path
prop and either a component
prop or children.
;
Beware: If multiple routes have a matching path, all will be shown. Use a Switch
if that's not desired.
As you can see, it's possible to specify a component to render or normal children.
You can even use a callback instead of children like this:
;
See further below for the the possibility of using parameters.
Switch
If you only want the first Route
that has a matching path to be shown, you can use a Switch
:
;
Note: The path pattern for the "Otherwise" Route differs depending on your route matching algorithm. With the built-in simpleRouteMatcherFactory
you would use "*"
, while you would use "(.*)"
or "/:fallback"
for path-to-regexp
.
Get parameters without being in a Route Component
You can get a memoized parameters object for the given path like this:
;
Custom Route Matching
This library doesn't force a route matching algorithm on you, but it comes with a lightweight one built-in.
The default route matching algorithm only allows exact matches and a match everything ("*").
If you need something more sophisticated, you'll have to supply a factory. Here is a simple example using the popular path-to-regexp library:
;; ;
Using pathToRegexp allows to extract named parameters from a pattern like "/users/:name". I.e. if the path is "/users/Zaphod", then the param with the key "name" would have the value "Zaphod".
Adding parameters
When you use a custom matching algorithm like the one above, you can extract values from the path. Let's say you have this route:
;
You defined a parameter :id in your path. Now you want to access it in your News
component:
;
Fresh Rendering
Let's say you have this route:
;
Moving from /news/1
to /news/2
will only update the components properties. State will be preserved.
If you want to force the component to be created from scratch in this situation, you can do so by setting the property addKey
(boolean).
This will add the key
property to the component with a value of the current path.
Storing the route in the hash instead
In some situations, it's easier to store the route in the hash part of the URL, as it avoids the server having to be aware of the single page application behavior. You can enable the "hash" mode on the Router
component:
;;
This will result in a url like https://some-domain.com/#/News
instead of https://some-domain.com/News
.
This approach will still use the history API internally!
Using a basename
If your app is not located at the root directory of a server, but instead in a sub-directory, you'll want to specify that sub-directory. You can do that on the Router
component.
Basename will be prefixed on Link
components.
;;
If you have a <base>
tag in your HTML, this can be easily detected using the getBasename()
helper. That way you don't have to hard-code it:
;;
Link
The Link
component can be used to change the url and still act as a normal <a>
tag, so you can open the link in a new tab.
;
Any extra props you pass in will be forwarded to the <a>
element. If you specify an onClick property and it calls preventDefault(), then the history change will not happen, as would be the case with any normal link.
LinkButton, etc.
If you want to create a LinkButton or similar, you can do that easily. This is the implementation of Link:
Creating a LinkButton
is as simple as this:
;...
RouterContext
Router
internally adds a RouterContext to your application, which you can access using the useRouter()
hook:
;...
RouterContextValue
is defined as:
// with:// and:;
urlTo()
can be used to create a new url, which respects basename
and mode
. It's the same for both RouterContextValue
and RouterHistory
.
Report isssues
Something not working quite as expected? Do you need a feature that has not been implemented yet? Check the issue tracker and add a new one if your problem is not already listed. Please try to provide a detailed description of your problem, including the steps to reproduce it.
Contribute
Awesome! If you would like to contribute with a new feature or submit a bugfix, fork this repo and send a pull request. Please, make sure all the unit tests are passing before submitting and add new ones in case you introduced new features.
License
react-router-ts has been released under the zlib/libpng license, meaning you can use it free of charge, without strings attached in commercial and non-commercial projects. Credits are appreciated but not mandatory.