0
# @vueuse/math
1

2
@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.
3

4
## Package Information
5

6
- **Package Name**: @vueuse/math
7
- **Package Type**: npm  
8
- **Language**: TypeScript
9
- **Installation**: `npm install @vueuse/math`
10

11
## Core Imports
12

13
```typescript
14
import { useAbs, useSum, useAverage, useClamp, useMath } from "@vueuse/math";
15
```
16

17
For individual function imports:
18

19
```typescript
20
import { useSum } from "@vueuse/math";
21
import { logicAnd, logicOr, logicNot } from "@vueuse/math";
22
import { createProjection, useProjection } from "@vueuse/math";
23
```
24

25
## Basic Usage
26

27
```typescript
28
import { ref } from "vue";
29
import { useSum, useAverage, useClamp, logicAnd } from "@vueuse/math";
30

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

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

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

45
console.log(sum.value);      // 15
46
console.log(average.value);  // 3
47
console.log(clamped.value);  // 10
48
console.log(result.value);   // false
49
```
50

51
## Architecture
52

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

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

61
## Core Types
62

63
```typescript { .api }
64
// From Vue
65
type MaybeRefOrGetter<T> = T | Ref<T> | ComputedRef<T> | (() => T);
66
type ComputedRef<T> = Readonly<Ref<Readonly<T>>>;
67

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

71
// Package-specific utility types
72
type MaybeComputedRefArgs<T> = MaybeRefOrGetter<T>[] | [MaybeRefOrGetter<MaybeRefOrGetter<T>[]>];
73
```
74

75
## Capabilities
76

77
### Basic Math Operations
78

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

81
```typescript { .api }
82
function useAbs(value: MaybeRefOrGetter<number>): ComputedRef<number>;
83
function useCeil(value: MaybeRefOrGetter<number>): ComputedRef<number>;
84
function useFloor(value: MaybeRefOrGetter<number>): ComputedRef<number>;
85
function useRound(value: MaybeRefOrGetter<number>): ComputedRef<number>;
86
function useTrunc(value: MaybeRefOrGetter<number>): ComputedRef<number>;
87
```
88

89
[Basic Math Operations](./basic-math.md)
90

91
### Aggregation Functions
92

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

95
```typescript { .api }
96
function useSum(array: MaybeRefOrGetter<MaybeRefOrGetter<number>[]>): ComputedRef<number>;
97
function useSum(...args: MaybeRefOrGetter<number>[]): ComputedRef<number>;
98

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

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

105
function useMin(array: MaybeRefOrGetter<MaybeRefOrGetter<number>[]>): ComputedRef<number>;
106
function useMin(...args: MaybeRefOrGetter<number>[]): ComputedRef<number>;
107
```
108

109
[Aggregation Functions](./aggregation.md)
110

111
### Value Control Functions
112

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

115
```typescript { .api }
116
function useClamp(
117
  value: ReadonlyRefOrGetter<number>,
118
  min: MaybeRefOrGetter<number>,
119
  max: MaybeRefOrGetter<number>
120
): ComputedRef<number>;
121

122
function useClamp(
123
  value: MaybeRefOrGetter<number>,
124
  min: MaybeRefOrGetter<number>,
125
  max: MaybeRefOrGetter<number>
126
): Ref<number>;
127

128
function usePrecision(
129
  value: MaybeRefOrGetter<number>,
130
  digits: MaybeRefOrGetter<number>,
131
  options?: MaybeRefOrGetter<UsePrecisionOptions>
132
): ComputedRef<number>;
133

134
interface UsePrecisionOptions {
135
  math?: 'floor' | 'ceil' | 'round';
136
}
137
```
138

139
[Value Control Functions](./value-control.md)
140

141
### Generic Math Operations
142

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

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

148
function useMath<K extends keyof Math>(
149
  key: K,
150
  ...args: ArgumentsType<Reactified<Math[K], true>>
151
): ReturnType<Reactified<Math[K], true>>;
152
```
153

154
[Generic Math Operations](./generic-math.md)
155

156
### Projection Utilities
157

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

160
```typescript { .api }
161
type ProjectorFunction<F, T> = (input: F, from: readonly [F, F], to: readonly [T, T]) => T;
162
type UseProjection<F, T> = (input: MaybeRefOrGetter<F>) => ComputedRef<T>;
163

164
function createProjection(
165
  fromDomain: MaybeRefOrGetter<readonly [number, number]>,
166
  toDomain: MaybeRefOrGetter<readonly [number, number]>,
167
  projector?: ProjectorFunction<number, number>
168
): UseProjection<number, number>;
169

170
function createGenericProjection<F = number, T = number>(
171
  fromDomain: MaybeRefOrGetter<readonly [F, F]>,
172
  toDomain: MaybeRefOrGetter<readonly [T, T]>,
173
  projector: ProjectorFunction<F, T>
174
): UseProjection<F, T>;
175

176
function useProjection(
177
  input: MaybeRefOrGetter<number>,
178
  fromDomain: MaybeRefOrGetter<readonly [number, number]>,
179
  toDomain: MaybeRefOrGetter<readonly [number, number]>,
180
  projector?: ProjectorFunction<number, number>
181
): ComputedRef<number>;
182
```
183

184
[Projection Utilities](./projection.md)
185

186
### Logical Operations
187

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

190
```typescript { .api }
191
function logicAnd(...args: MaybeRefOrGetter<any>[]): ComputedRef<boolean>;
192
function logicOr(...args: MaybeRefOrGetter<any>[]): ComputedRef<boolean>;
193
function logicNot(v: MaybeRefOrGetter<any>): ComputedRef<boolean>;
194

195
// Aliases
196
const and: typeof logicAnd;
197
const or: typeof logicOr;
198
const not: typeof logicNot;
199
```
200

201
[Logical Operations](./logical.md)