or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

aggregation.mdbasic-math.mdgeneric-math.mdindex.mdlogical.mdprojection.mdvalue-control.md
tile.json

tessl/npm-vueuse--math

Reactive mathematical utility functions and composables for Vue.js applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@vueuse/math@13.9.x

To install, run

npx @tessl/cli install tessl/npm-vueuse--math@13.9.0

index.mddocs/

@vueuse/math

@vueuse/math provides reactive mathematical utility functions and composables for Vue.js applications. It includes reactive wrappers for basic math operations, aggregation functions, value control utilities, generic math operations, projection utilities, and logical operations - all designed to work seamlessly with Vue's reactivity system.

Package Information

  • Package Name: @vueuse/math
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @vueuse/math

Core Imports

import { useAbs, useSum, useAverage, useClamp, useMath } from "@vueuse/math";

For individual function imports:

import { useSum } from "@vueuse/math";
import { logicAnd, logicOr, logicNot } from "@vueuse/math";
import { createProjection, useProjection } from "@vueuse/math";

Basic Usage

import { ref } from "vue";
import { useSum, useAverage, useClamp, logicAnd } from "@vueuse/math";

// Reactive mathematical operations
const numbers = ref([1, 2, 3, 4, 5]);
const sum = useSum(numbers);           // ComputedRef<number>
const average = useAverage(numbers);   // ComputedRef<number>

// Value clamping
const value = ref(15);
const clamped = useClamp(value, 0, 10); // Keeps value between 0-10

// Logical operations
const condition1 = ref(true);
const condition2 = ref(false);
const result = logicAnd(condition1, condition2); // ComputedRef<boolean>

console.log(sum.value);      // 15
console.log(average.value);  // 3
console.log(clamped.value);  // 10
console.log(result.value);   // false

Architecture

@vueuse/math is built around Vue's reactivity system using several key patterns:

  • Reactive Wrappers: Each function wraps native JavaScript Math methods with Vue's computed() for automatic reactivity
  • Flexible Input Types: All functions accept MaybeRefOrGetter<T> types, allowing refs, getters, or plain values
  • Type Safety: Full TypeScript integration with proper generic types and function overloads
  • Composable Pattern: Functions follow Vue 3 composition API patterns for maximum reusability
  • Zero Dependencies: Only depends on Vue and @vueuse/shared utilities

Core Types

// From Vue
type MaybeRefOrGetter<T> = T | Ref<T> | ComputedRef<T> | (() => T);
type ComputedRef<T> = Readonly<Ref<Readonly<T>>>;

// From @vueuse/shared
type ReadonlyRefOrGetter<T> = MaybeRefOrGetter<T> | Readonly<Ref<T>>;

// Package-specific utility types
type MaybeComputedRefArgs<T> = MaybeRefOrGetter<T>[] | [MaybeRefOrGetter<MaybeRefOrGetter<T>[]>];

Capabilities

Basic Math Operations

Reactive wrappers for fundamental JavaScript Math methods including absolute value, ceiling, floor, rounding, and truncation.

function useAbs(value: MaybeRefOrGetter<number>): ComputedRef<number>;
function useCeil(value: MaybeRefOrGetter<number>): ComputedRef<number>;
function useFloor(value: MaybeRefOrGetter<number>): ComputedRef<number>;
function useRound(value: MaybeRefOrGetter<number>): ComputedRef<number>;
function useTrunc(value: MaybeRefOrGetter<number>): ComputedRef<number>;

Basic Math Operations

Aggregation Functions

Functions for calculating sums, averages, minimums, and maximums from arrays or multiple arguments with full reactivity.

function useSum(array: MaybeRefOrGetter<MaybeRefOrGetter<number>[]>): ComputedRef<number>;
function useSum(...args: MaybeRefOrGetter<number>[]): ComputedRef<number>;

function useAverage(array: MaybeRefOrGetter<MaybeRefOrGetter<number>[]>): ComputedRef<number>;
function useAverage(...args: MaybeRefOrGetter<number>[]): ComputedRef<number>;

function useMax(array: MaybeRefOrGetter<MaybeRefOrGetter<number>[]>): ComputedRef<number>;
function useMax(...args: MaybeRefOrGetter<number>[]): ComputedRef<number>;

function useMin(array: MaybeRefOrGetter<MaybeRefOrGetter<number>[]>): ComputedRef<number>;
function useMin(...args: MaybeRefOrGetter<number>[]): ComputedRef<number>;

Aggregation Functions

Value Control Functions

Utilities for clamping values within bounds and controlling numerical precision with configurable rounding methods.

function useClamp(
  value: ReadonlyRefOrGetter<number>,
  min: MaybeRefOrGetter<number>,
  max: MaybeRefOrGetter<number>
): ComputedRef<number>;

function useClamp(
  value: MaybeRefOrGetter<number>,
  min: MaybeRefOrGetter<number>,
  max: MaybeRefOrGetter<number>
): Ref<number>;

function usePrecision(
  value: MaybeRefOrGetter<number>,
  digits: MaybeRefOrGetter<number>,
  options?: MaybeRefOrGetter<UsePrecisionOptions>
): ComputedRef<number>;

interface UsePrecisionOptions {
  math?: 'floor' | 'ceil' | 'round';
}

Value Control Functions

Generic Math Operations

Generic reactive wrapper that provides access to any Math method with full type safety and reactive behavior.

type UseMathKeys = keyof { [K in keyof Math as Math[K] extends (...args: any) => any ? K : never]: unknown };

function useMath<K extends keyof Math>(
  key: K,
  ...args: ArgumentsType<Reactified<Math[K], true>>
): ReturnType<Reactified<Math[K], true>>;

Generic Math Operations

Projection Utilities

Functions for mapping values between different numerical ranges, useful for data visualization, animations, and value transformations.

type ProjectorFunction<F, T> = (input: F, from: readonly [F, F], to: readonly [T, T]) => T;
type UseProjection<F, T> = (input: MaybeRefOrGetter<F>) => ComputedRef<T>;

function createProjection(
  fromDomain: MaybeRefOrGetter<readonly [number, number]>,
  toDomain: MaybeRefOrGetter<readonly [number, number]>,
  projector?: ProjectorFunction<number, number>
): UseProjection<number, number>;

function createGenericProjection<F = number, T = number>(
  fromDomain: MaybeRefOrGetter<readonly [F, F]>,
  toDomain: MaybeRefOrGetter<readonly [T, T]>,
  projector: ProjectorFunction<F, T>
): UseProjection<F, T>;

function useProjection(
  input: MaybeRefOrGetter<number>,
  fromDomain: MaybeRefOrGetter<readonly [number, number]>,
  toDomain: MaybeRefOrGetter<readonly [number, number]>,
  projector?: ProjectorFunction<number, number>
): ComputedRef<number>;

Projection Utilities

Logical Operations

Reactive logical operations including AND, OR, and NOT with support for multiple arguments and aliased exports.

function logicAnd(...args: MaybeRefOrGetter<any>[]): ComputedRef<boolean>;
function logicOr(...args: MaybeRefOrGetter<any>[]): ComputedRef<boolean>;
function logicNot(v: MaybeRefOrGetter<any>): ComputedRef<boolean>;

// Aliases
const and: typeof logicAnd;
const or: typeof logicOr;
const not: typeof logicNot;

Logical Operations