use-counter

Create a clamped counter whose every transition stays inside [min, max].


Package	`@vizejs/composable/use-counter`
Own the source	`vize lib pull composable:use-counter`
Runtime exports	`useCounter`
Gzip budget	1536 B

Usage

import { useCounter } from "@vizejs/composable/use-counter";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useCounter`	state	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	—	—

API

`useCounter`

Create a clamped counter whose every transition stays inside [min, max]. All operations clamp instead of failing, including the initial value, so the count is inside the bounds at every observable moment. Only NaN is rejected — silently corrupting the count is never an option. Purely synchronous state: safe during server rendering (no browser globals, no timers) and nothing to dispose, so it works inside and outside reactive scopes alike. Bounds are fixed at creation and not reactive.

function useCounter(initial = 0, options: UseCounterOptions = {}): CounterControls

const { count, increment, atMax } = useCounter(9, { min: 0, max: 10 });
increment(); // 10
increment(); // 10 (clamped)
atMax.value; // true

Types

`UseCounterOptions`

Options for useCounter.

Member	Type	Description
`min`?	`number`	Inclusive lower bound applied to every value the counter takes.
`max`?	`number`	Inclusive upper bound applied to every value the counter takes.

`CounterControls`

Reactive controls returned by useCounter.

Member	Type	Description
`count`	`Readonly<ShallowRef<number>>`	Current count. Changes only through the controls, never by assignment.
`atMin`	`ComputedRef<boolean>`	Whether the count currently sits on the configured lower bound.
`atMax`	`ComputedRef<boolean>`	Whether the count currently sits on the configured upper bound.
`increment`	`(delta?: number) => number`	Add `delta` (default `1`) to the count and clamp into the bounds.
`decrement`	`(delta?: number) => number`	Subtract `delta` (default `1`) from the count and clamp into the bounds.
`set`	`(value: number) => number`	Assign a value directly, clamped into the bounds.
`reset`	`(value?: number) => number`	Restore the reset baseline, or establish a new one. Without an argument the count returns to the creation-time initial value (after its original clamping). With an argument, the clamped value becomes both the new count and the baseline used by later `reset()` calls.