# better-state

> A small wrapper that encapsulates history.pushState and window.onpopstate and offers extra features - including 'No Going Back'

Latest version **1.1.9** (published 2022-05-01) · Help yourself license · 0 weekly downloads

## Install

```sh
npm install better-state
pnpm add better-state
yarn add better-state
bun add better-state
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.9 |
| Published | 2022-05-01 |
| First published | 2022-04-10 |
| Weekly downloads | 0 |
| License | Help yourself |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 14.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | weepingboil |
| Maintainers | weepingboil |
| Keywords | back button, history, prevent, back, browser, pushState, onpopstate |

## Links

- npm: https://www.npmjs.com/package/better-state
- npm.io page: https://npm.io/package/better-state

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 1.1.9 (latest) — 2022-05-01
- 1.1.7 — 2022-05-01
- 1.1.6 — 2022-04-11
- 1.1.5 — 2022-04-11
- 1.1.4 — 2022-04-11
- 1.1.3 — 2022-04-11
- 1.1.2 — 2022-04-11
- 1.1.1 — 2022-04-11
- 1.1.0 — 2022-04-11
- 1.0.63 — 2022-04-10
- 1.0.62 — 2022-04-10
- 1.0.61 — 2022-04-10
- 1.0.60 — 2022-04-10
- 1.0.10 — 2022-04-10
- 1.0.57 — 2022-04-10
- … 11 more at https://npm.io/package/better-state/versions

## README

# Better-State

#### Including "No Going Back"

This is a small wrapper that encapsulates

* [history.pushState()](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState)
* [history.replaceState()](https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState), and
* [window.onpopstate()](https://developer.mozilla.org/en-US/docs/Web/API/WindowEventHandlers/onpopstate)

  

## Features

1. View the browser history[^1] for your app.
2. Prevent the use of the browser's back and forward buttons.
  ("No Going Back")
3. Get more information in the onpopstate event, such as whether the back button or forward button was pressed...
4. Includes the current window.scroll for convenience (useful when using [History.scrollRestoration  = 'manual'](https://developer.mozilla.org/en-US/docs/Web/API/History/scrollRestoration))

  
## Installation

`npm install better-state`

  
## Setup

`import betterState from "better-state";`


---


## Known Issues

Preventing the browser back button is a bit of a hack - and definitely not supported by most modern browsers.

Please test thoroughly before using in a production environment.

(Because it's not possible to actually prevent the back button event, **better-state** forces an immediate history.go(1)  )


---


## Usage

To change the current browser URL and add to the browser history:

`betterState.pushState(url)`

`betterState.pushState(url,{--some consumer-data})`


---


To prevent the use of the browser's back and forward buttons:

  ("No Going Back")

`betterState.preventBack = true`

`betterState.preventForward = true`

NB - effects of this settings are stacked and cumulative. ie **two** calls to `betterState.preventBack = true` will require two calls to `betterState.preventBack = false` to take affect. Use `betterState.resetPreventBack()` and `betterState.resetPreventForward()` to negate previous calls.


---


To get the current known history[^1]:

`betterState.history`


---


To subscribe to popstate events (i.e. back and forward button clicks...)

`betterState.onPopState = (e) => { console.log(e); };`

returns:
- back: [ *true | false* ] if the back button was pressed.
- forward: [ *true | false* ] if the forward button was pressed.
- prevented: [ *true | false* ] if the pop was prevented.
- forced: [ *true | false* ] if the pop was forced[^2]
- state: { _Object_ } including:
  - url
  - scrollX
  - scrollY
  - data: { _Object_ } any consumer data


---


To unsubscribe

`betterState.offPopState();`



---



To override `preventBack` and `preventForward`:

`betterState.forceForward()`

`betterState.forceBack()`


---


To replace the current state:

  (i.e. to change the current URL without adding to the browser history)

`betterState.replaceState(url)`

`betterState.replaceState(url,{--some consumer-data})`


---


To get the current state:

`betterState.state`


---


[^1]: Only includes better-state history.

[^2]: See forceBack() and forceForward().

---
_Source: https://npm.io/package/better-state · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._