Home
Router for Web Components
Works with Polymer, X-Tag, and natively.
Manage page state. Lazy-load content. Data-bind path variables and query parameters. Use multiple layouts. Navigate with hashchange and HTML5 pushState. Animate transitions using core-animated-pages.
Download or run bower install app-router --save
Configuration #
Define how URLs map to pages.
<!doctype html>
<html>
<head>
<title>App Router</title>
<link rel="import" href="/bower_components/app-router/app-router.html">
</head>
<body>
<app-router>
<!-- matches an exact path -->
<app-route path="/home" imp="../../../packages/app_router_test/pages/home-page.html"></app-route>
<!-- matches using a wildcard -->
<app-route path="/customer/*" imp="../../../packages/app_router_test/pages/customer-page.html"></app-route>
<!-- matches using a path variable -->
<app-route path="/order/:id" imp="../../../packages/app_router_test/pages/order-page.html"></app-route>
<!-- matches a pattern like '/word/number' -->
<app-route path="/^\/\w+\/\d+$/i" regex imp="../../../packages/app_router_test/pages/regex-page.html"></app-route>
<!-- matches everything else -->
<app-route path="*" imp="../../../packages/app_router_test/pages/not-found-page.html"></app-route>
</app-router>
</body>
</html>Navigation #
Click links or call router.go().
<!-- hashchange -->
<a href="/#/home">Home</a>
<!-- pushState() -->
<a is="pushstate-anchor" href="/home">Home</a>
<!-- router.go(path, options) -->
<script>
document.querySelector('app-router').go('/home');
</script>The router listens to popstate and hashchange events. Changing the URL will find the first app-route that matches, load the element or template, and replace the current view.
hashchange #
Clicking <a href="/#/home">Home</a> will fire a hashchange event and tell the router to load the first route that matches /home. You don't need to handle the event in your Javascript. Hash paths /#/home match routes without the hash <app-route path="/home">.
pushState #
You can use the pushstate-anchor or html5-history-anchor to extend <a> tags with the HTML5 history API.
<a is="pushstate-anchor" href="/home">Home</a>This will call pushState() and dispatch a popstate event.
Note: You need to make sure the server returns index.html when looking up the resource at /home. The simplest set up is to always return index.html and let the app-router handle the routing including a not found page.
go(path, options) #
You can navigate imperatively using Javascript.
document.querySelector('app-router').go('/home');
// or
document.querySelector('app-router').go('/home', {replace: true});See the navigation examples here app-router-examples.
Data Binding #
Path variables and query parameters automatically attach to the element's attributes.
<!-- url -->
<a is="pushstate-anchor" href="/order/123?sort=ascending">Order 123</a>
<!-- route -->
<app-route path="/order/:id" imp="../../../packages/app_router_test/pages/order-page.html"></app-route>
<!-- will bind 123 to the page's `id` attribute and "ascending" to the `sort` attribute -->
<order-page id="123" sort="ascending"></order-page>See it in action here.
Notes #
Check the change log for breaking changes in major versions.
Compare app-router, flatiron-director, and plain old HTML files https://github.com/erikringsmuth/polymer-router-demos.