use-counter

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

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

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

Try it

Reserve workshop seats

Keep a seat quantity between one and five and explain why further changes are unavailable.

Open the interactive example

What to observe: Add seats until the limit message appears. Add and remove controls disable at their respective bounds; Reset restores the initial one-seat reservation.

Mutate the readonly count through its controls. atMin and atMax are computed refs. Bounds are fixed when the composable is created.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useCounter } from "@vizejs/composable/use-counter";

const { count, atMin, atMax, increment, decrement, reset } = useCounter(1, { min: 1, max: 5 });
</script>

<template>
  <div class="composable-example">
    <p>Reserve up to five workshop seats.</p>
    <div class="example-actions">
      <button type="button" :disabled="atMin" @click="() => decrement()">Remove seat</button>
      <output aria-live="polite">{{ count }} {{ count === 1 ? "seat" : "seats" }}</output>
      <button type="button" :disabled="atMax" @click="() => increment()">Add seat</button>
      <button type="button" @click="() => reset()">Reset seats</button>
    </div>
    <p v-if="atMax">You reached the five-seat limit.</p>
  </div>
</template>

Runtime contract

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.

CounterControls

Reactive controls returned by useCounter.