Skip to content

Latest commit

 

History

History
152 lines (114 loc) · 4.17 KB

README.md

File metadata and controls

152 lines (114 loc) · 4.17 KB
Raw

VanJS Routing

The cleanest, simplest declarative routing solution for the VanJS framework. If you are coming from React, vanjs-routing feels similar to react-router.

Install

yarn add vanjs-routing vanjs-core
npm i -S vanjs-routing vanjs-core

Features

  1. Declare routes with Router() using a clean, simple and concise syntax
  2. Use Link() instead of a() to navigate between pages
  3. Use navigate() in areas Link cannot be used. (E.g. In a side-effect)
  4. Access the router internal state
    • Get the current pathname with getRouterPathname()
    • Get the dynamic URL parameters with getRouterParams()
    • Get the query parameters with getRouterQuery()
  5. Supports dynamic URLs (E.g. /help/:section/:topic) with getRouterParams()
  6. Supports URL prefixing using Router.basename. (Useful for sites like Github Pages)

QuickStart

import van from "vanjs-core";
import { Router, Link, getRouterParams, navigate } from "vanjs-routing";

const { div, p, button } = van.tags;

function App() {
  return Router({
    basename: "vanjs-routing", // Optional base name (All links are now prefixed with '/vanjs-routing')
    routes: [
      { path: "/", component: HomeComponent },
      { path: "/about", component: AboutComponent },
      { path: "/help/:section", component: HelpComponent }
    ]
  });
}

function HomeComponent() {
  return div(p("Home"), Link({ href: "/about?foo=bar" }, "Goto About"), Link({ href: "/help/profile" }, "Goto Help"));
}

function AboutComponent() {
  return div(p("About"), Link({ href: "/" }, "Back to Home"));
}

function HelpComponent() {
  van.derive(() => {
    console.log(getRouterParams()); // { section: "profile" }
  });

  return div(
    p("Help"),
    Link({ href: "/" }, "Back to Home"),
    button({ onclick: () => navigate("/") }, "Back to Home (Imperative navigation)")
  );
}

van.add(document.body, App());

API Reference

Router

  • The Router component which you use to define your routes
  • Each route is an object with a path and component
    • The component is a function returning an HTMLElement
import { Router } from "vanjs-routing";

Router({
  basename?: string,
  routes: Array <{
    path: string,
    component: () => HTMLElement
  }>
});

Link

  • The Link extends the van.tags.a component to tap into the router's internal state for navigation
  • Link is a drop-in replacement for van.tags.a
  • If replace is set to true, the current route will be replaced with the Link's href when clicked
import { Link } from "vanjs-routing";

Link({
  replace?: boolean
  // Additional van.tags.a props
});

Navigate

  • The navigate function is useful in areas where Link cannot be used. For example in a function or side-effect
  • If replace is set to true, the current route will be replaced with href instead of pushing to the history stack.
import { navigate } from "vanjs-routing";

navigate(
  href,
  options ?: {
    replace?: boolean
  }
)

Router state helpers

  • getRouterPathname() returns the current pathname
  • getRouterParams() returns the parameter values in a dynamic route
  • getRouterQuery() returns the query parameters
import { getRouterPathname, getRouterParams, getRouterQuery } from "vanjs-routing";

// Route path:    /home/:section/:topic
// Current URL:   https://hello.com/home/learning/science?tab=intro

console.log(getRouterPathname()); // "/home/learning/science"
console.log(getRouterParams()); // { section: "learning", topic: "science" }
console.log(getRouterQuery()); // { tab: "intro" }

Contributors

Change Log

  • 1.1.3
    • Update package.json metadata and README documentation
  • 1.1.2
    • Update README documentation
  • 1.1.0
    • Added basename prop to Router component.