Backbone Router Example
The fastest way to understand a Backbone router is to run one. This page is a complete, copy-paste example: a tiny single page application with three routes that swap content without reloading the browser. Everything is in one HTML file, uses the same Backbone.js 1.6.0 and Underscore the rest of this site references, and works if you open it locally with a simple static server.
Read the explainer first if routes are new to you, then come back here to see the idea in working code. The companion concept page is what is a router in Backbone.js.
What you'll learn
What this example builds
The result is a three-page application, home, about, and a dynamic user page, that updates the visible content as the URL hash changes, with no full page reload.
The behaviour you will see
Clicking the navigation links changes the URL to #home, #about, or #user/42, and the content area swaps instantly. The last route carries a parameter, the user id, which the handler reads and prints. This is the core of every client-side router: map a URL pattern to a function, and run that function when the pattern matches.
The HTML page setup
Everything lives in one file. The head loads the three dependencies, and the body holds the navigation and an empty container the router will fill.
The page skeleton
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Backbone Router Example</title>
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.13.6/underscore-min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/backbone.js/1.6.0/backbone-min.js"></script>
</head>
<body>
<nav>
<a href="#home">Home</a>
<a href="#about">About</a>
<a href="#user/42">User 42</a>
</nav>
<div id="content"></div>
<script>/* router code goes here */</script>
</body>
</html>The router and handlers
This is the part that matters. The router declares its routes as a map of patterns to method names, and each method updates the content container.
The router definition
var AppRouter = Backbone.Router.extend({
routes: {
"home": "showHome",
"about": "showAbout",
"user/:id": "showUser"
},
showHome: function () {
$("#content").html("<h1>Home</h1>");
},
showAbout: function () {
$("#content").html("<h1>About</h1>");
},
showUser: function (id) {
$("#content").html("<h1>User " + _.escape(id) + "</h1>");
}
});
var app = new AppRouter();
Backbone.history.start();How it works, line by line
Four things happen, and understanding their order is the whole lesson.
From hash change to rendered view
First, the routes map pairs each URL pattern with a handler name, and the :id token marks a parameter. Second, Backbone.history.start() begins listening for hash changes and immediately fires the handler for the current URL. Third, when the hash changes, Backbone matches it against the patterns top to bottom and calls the first match. Fourth, the handler receives any parameters as arguments, so showUser gets 42 from #user/42. The matching and dispatch are automatic once history is started.
Running and extending it
Open the file through a static server rather than the file system, because some browsers restrict hash routing on file:// URLs.
A one-line local server
# from the folder containing the HTML file
python3 -m http.server 8000
# then visit http://localhost:8000 in your browserTo extend it, add a route such as "search/:q": "showSearch" and a matching method, or render a real Backbone view inside each handler instead of writing HTML directly. For a larger structure, see how routers fit with models and collections in the Backbone model example.
Common pitfalls
Three mistakes account for most broken Backbone routers, and all are easy to avoid once named.
What usually goes wrong
The most common is forgetting Backbone.history.start(), without which no route ever fires and the page stays blank. The second is route order: more specific patterns must come before catch-all ones, since Backbone uses the first match. The third is dropping the parameter, defining the route as "user/:id" but writing a handler that takes no argument, so the id is silently ignored. Escaping user-supplied values with _.escape before inserting them, as shown above, also prevents a cross-site scripting hole. The deeper routing model is covered in what is a router.
Frequently Asked Questions
How do I run this Backbone router example?
Save it as a single HTML file and serve it through a static server, for example python3 -m http.server 8000, then visit the local address. Hash routing can misbehave when opened directly from the file system.
How do route parameters work in Backbone?
A token like :id in a route pattern such as user/:id captures that part of the URL and passes it to the handler as an argument. So visiting user/42 calls the handler with 42.
Why is my Backbone router not working?
The most common cause is forgetting to call Backbone.history.start(), without which no route fires. Also check that specific routes come before catch-all routes, since Backbone uses the first match.
Should I render views inside route handlers?
For anything beyond a demo, yes. Have each handler create or update a Backbone view rather than writing HTML directly, which keeps rendering logic organised as the application grows.
Read next: the Backbone model example, or back to the Examples hub.
Want the concept behind the code?
The router explainer walks through navigation, routes, and how the pieces connect.
Read: What is a Router →