https://github.com/substrate-system/route-event
Simple client side route event
https://github.com/substrate-system/route-event
Last synced: about 1 year ago
JSON representation
Simple client side route event
- Host: GitHub
- URL: https://github.com/substrate-system/route-event
- Owner: substrate-system
- License: mit
- Created: 2024-02-04T18:12:23.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-08T02:11:13.000Z (over 1 year ago)
- Last Synced: 2025-03-24T06:51:45.734Z (about 1 year ago)
- Language: TypeScript
- Size: 82 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# route event
[](https://github.com/bicycle-codes/route-event/actions/workflows/nodejs.yml)
[](README.md)
[](README.md)
[](https://semver.org/)
[](LICENSE)
Simple route event for the browser. This will handle URL changes client-side, so that navigating will not cause a page reload.
Call a function with a path whenever someone clicks a link that is local to the server. Also, use the [history API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to handle back/forward button clicks.
## install
```sh
npm i -S route-event
```
### CJS
```js
var Route = require('route-event').default
```
### ESM
```js
import Route from 'route-event'
```
## example
Listen for click events on `document.body`. If the event is triggered by using
the browser's back/forward button, then `{ popstate }` will be true.
```js
import Route from 'route-event'
const onRoute = Route() // by default listen on document.body
// listen for click events on docuement.body. If the href is local to the
// server, call `onRoute`
var stopListening = onRoute(function onRoute (path, data) {
console.log(path)
// => '/example/path'
console.log(data)
// => { scrollX: 0, scrollY: 0, popstate: false }
// handle scroll state like a web browser
// (restore scroll position on back/forward)
if (data.popstate) {
return window.scrollTo(data.scrollX, data.scrollY)
}
// if this was a link click (not back button), then scroll to top
window.scrollTo(0, 0)
})
// programmatically change the location and call the onRoute cb
routeEvent.setRoute('/some/path')
// change the route, but don't call the callbacks
routeEvent.setRoute.push('/abc')
// ...sometime in the future...
// unsubscribe from route events
stopListening()
```
Pass in an element to listen to, and handle events with a router:
```js
import Route from 'route-event'
import Router from '@substrate-system/routes'
const router = Router()
const routeEvent = Route({
el: document.getElementById('example')
})
router.addRoute('/', function () {
console.log('root')
})
routeEvent(function onChange (path, ev) {
var m = router.match(path)
m.action()
// handle scroll state like a web browser
if (ev.popstate) {
return window.scrollTo(ev.scrollX, ev.scrollY)
}
window.scrollTo(0, 0)
})
```
## API
### Listener
Event listeners are functions that take an `href` and an object with previous
scroll position and `popstate` -- a boolean indicating if this was a link
click or back / forward button (`true` means it was back/forward button).
```ts
interface Listener {
(href:string, data:{
scrollX:number,
scrollY:number,
popstate:boolean
}):void;
}
```
### Route
Create an instance of the event listener. Optionally take an element to listen to. Return a function that takes a callback that will receive route events. The returned function also has a property `setRoute` that will prgrammatically change the URL and call any route listeners.
```js
import Route from 'route-event'
```
```ts
function Route (opts:{ el?:HTMLElement } = {}):{
(cb:Listener):void;
setRoute:ReturnType
}
```
### setRoute
A property on the returned function so you can programmatically set the URL.
```ts
function setRoute (href:string):void
```
```js
import Route from '@substrate-system/route-event'
const routeEvent = Route()
routeEvent.setRoute('/example')
```
### `setRoute.push`
Change the route, but don't call the callbacks.
```ts
import Route from '@substrate-system/route-event'
const routeEvent = Route()
routeEvent.setRoute.push = function (href:string):void {
```