Router options

router5
Guides Integration GitHub
Search…
Read Me
Router options
You can configure your router instance by passing options to the constructor or by using .setOption(optName, optValue).
var router = createRouter([], {
    allowNotFound: false,
    autoCleanUp: true,
    defaultRoute: 'home',
    defaultParams: {},
    queryParams: {
        arrayFormat: 'default',
        nullFormat: 'default',
        booleanFormat: 'default'
    },
    queryParamsMode: 'default',
    trailingSlashMode: 'default',
    strictTrailingSlash: false,
    caseSensitive: false,
    urlParamsEncoding: 'default'
})
Default route
When your router instance starts, it will navigate to a default route if such route is defined and if it cannot match the URL against a known route:
defaultRoute: the default route.
defaultParams: the default route params (defaults to {})
See navigation guide for more information.
Allow not found
There are two ways to deal with not found routes: the first one is to configure a defaultRoute (and defaultParams), the second one is to allow those not found routes to create a new routing state. Set allowNotFound to true and the router will emit a state value for unmatched paths.
For example, if you try to match /hello-world and you don't have this route defined, the router will emit the following state:
import { constants } from 'router5';
​
const state = {
    name: constants.UNKNOWN_ROUTE
    params: { path: '/hello-world' },
    path: '/hello-world'
}
URL parameters encoding and decoding
Option urlParamsEncoding controls the encoding and decoding of URL parameters, when matching and building paths. It supports the following values:
'default': encodeURIComponent and decodeURIComponent are used but some characters to encode and decode URL parameters, but some characters are preserved when encoding (sub-delimiters:+,:,',!,,,;,*).
'uriComponent': use encodeURIComponent and decodeURIComponent for encoding and decoding URL parameters.
'uri': use encodeURI and decodeURI for encoding and decoding URL parameters.
'none': no encoding or decoding is performed
'legacy': the approach for version 5.x and below (no longer recommended to use)
Query parameters mode
Option queryParamsMode can take the following values:
'default': a path will match with any query parameters added, but when building, extra parameters won't appear in the returned path.
'strict': a path with query parameters which were not listed in node definition will cause a match to be unsuccessful. When building, extra parameters won't appear in the returned path.
'loose': a path will match with any query parameters added, and when building, extra parameters will appear in the returned path.
Query parameters formatting
You can specify how array, boolean and null values are formatted in query parameters, and how they are matched.
arrayFormat: Specifies how arrays should be stringified
'none' (default): no brackets or indexes are added to query parameter names ('role=member&role=admin')
'brackets: brackets are added to query parameter names ('role[]=member&role[]=admin')
'index': brackets and indexes are added to query parameter names ('role[0]=member&role[1]=admin')
booleanFormat: specifies how boolean values are stringified and parsed
'none' (default): booleans are stringified to strings ('istrue=true&isfalse=false')
'empty-true': same as 'none' except true values are stringified without value ('istrue&isfalse=false'). If you choose this boolean format, make sure to change the value of 'nullFormat'.
'string': same as 'none' but 'true' and 'false' are parsed as booleans
'unicode': true and false are displayed with unicode characters, and parsed as booleans ('istrue=✓&isfalse=✗')
nullFormat: specifies how null values are stringified and parsed
'default' (default): null values are stringified without equal sign and value ('isnull')
'string': null values are stringified to 'null' ('isnull=null') and parsed as null values
'hidden': null values are not stringified
Trailing slash mode
Option trailingSlashMode can take the following values:
'default': building follows path definitions
'never': when building, trailing slash is removed
'always': when building, trailing slash is added
Strict trailing slash
By default, the router is not in "strict match" mode. If you want trailing slashes to not be optional, you can set strictTrailingSlash to `true``.
Automatic clean up
If autoCleanUp is set to true, the router will automatically clear canDeactivate functions / booleans when their associated segment becomes inactive.
Case sensitivity
By default, matching of routes is case insensitive. You can set caseSensitive to true if you want to change that behaviour.
Path Syntax
Navigating
Last modified 2yr ago
Copy link
Outline
Default route
Allow not found
URL parameters encoding and decoding
Query parameters mode
Query parameters formatting
Trailing slash mode
Strict trailing slash
Automatic clean up
Case sensitivity