Router classThe Router class is the only thing you need to get started
with Vaadin.Router. Depending on your project setup, there are several
ways to access it.
In modern browsers that support ES modules the
Router class can be imported directly into a script tag on a page:
<script type="module">
import {Router} from 'https://unpkg.com/@vaadin/router';
</script>In Webpack / Rollup / Polymer CLI projects the Router class can
be imported from the @vaadin/router npm package:
import {Router} from '@vaadin/router';
In older browsers without the ES modules support the
Router class is exposed as a member of the Vaadin
namespace after the vaadin-router UMD bundle is loaded:
<script src="https://unpkg.com/@vaadin/router/dist/vaadin-router.umd.min.js"></script>
<script>
var Router = Vaadin.Router;
</script>Vaadin.Router automatically listens to navigation events and
asynchronously renders a matching Web Component into the given DOM node
(a.k.a. the router outlet). By default, navigation events are
triggered by popstate events on the window, and
by click events on <a> elements on the
page.
The routes config maps URL paths to Web Components. Vaadin.Router goes through the routes until it finds the first match, creates an instance of the route component, and inserts it into the router outlet (replacing any pre-existing outlet content). For details on the route path syntax see the Route Parameters demos.
Route components can be any Web Components regardless of how they are built: vanilla JavaScript, Polymer, Stencil, SkateJS, Angular, Vue, etc.
Vaadin.Router follows the lifecycle callbacks convention described in WebComponentInterface: if a route component defines any of these callback methods, Vaadin.Router will call them at the appropriate points in the navigation lifecycle. See the Lifecycle Callbacks section for more details.
In addition to that Vaadin.Router also sets a
location
property on every route Web Component so that you could access the
current location details via an instance property (e.g.
this.location.pathname).
If Vaadin.Router does not find a matching route, the promise returned
from the render() method gets rejected, and any content in
the router outlet is removed. In order to show a user-friendly 'page not
found' view, a fallback route with a wildcard '(.*)' path can
be added to the end of the routes list.
There can be different fallbacks for different route prefixes, but since the route resolution is based on the first match, the fallback route should always be after other alternatives.
The path that leads to the fallback route is available to the route
component via the location.pathname property.
Each route can have child routes, which makes it easier to group related routes together under a common parent. This is optional, i.e. the same routes config can be expressed as a flat list, or as a parent-children tree. The routes config in the example below is effectively the same as in the "Getting Started" example above.
The leading '/' in child route paths is optional—they
are always relative to the path of the parent route.
In certain cases, for instance when creating a navigation bar shown on certain application pages,
it is useful to define a common layout and reuse it. Vaadin.Router supports this by specifying
the component property both in parent and child route objects.
In this case child route's component will be rendered as a light DOM child of parent route's component.
When using Web Components, in order to display the children rendered by Vaadin.Router, parent component should contain
the <slot>
tag in its Shadow DOM. The parent layout component stays in the DOM when you switch between the child routes.