0
# Aggregation Functions
1

2
Functions for calculating sums, averages, minimums, and maximums from arrays or multiple arguments with full reactivity. All aggregation functions support both array inputs and spread arguments.
3

4
## Capabilities
5

6
### useSum
7

8
Reactively calculates the sum of numbers from an array or multiple arguments.
9

10
```typescript { .api }
11
/**
12
 * Get the sum of a set of numbers from an array
13
 * @param array - Array of reactive numbers or refs
14
 * @returns ComputedRef containing the sum
15
 */
16
function useSum(array: MaybeRefOrGetter<MaybeRefOrGetter<number>[]>): ComputedRef<number>;
17

18
/**
19
 * Get the sum of a set of numbers from multiple arguments
20
 * @param args - Multiple reactive numbers or refs
21
 * @returns ComputedRef containing the sum
22
 */
23
function useSum(...args: MaybeRefOrGetter<number>[]): ComputedRef<number>;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { ref } from "vue";
30
import { useSum } from "@vueuse/math";
31

32
// Array approach
33
const numbers = ref([1, 2, 3, 4, 5]);
34
const sum1 = useSum(numbers);
35
console.log(sum1.value); // 15
36

37
// Spread arguments approach
38
const a = ref(10);
39
const b = ref(20);
40
const c = ref(30);
41
const sum2 = useSum(a, b, c);
42
console.log(sum2.value); // 60
43

44
// Mixed with plain values
45
const sum3 = useSum(a, 5, b);
46
console.log(sum3.value); // 35
47

48
// Nested reactive arrays
49
const nestedArray = ref([ref(1), ref(2), ref(3)]);
50
const sum4 = useSum(nestedArray);
51
console.log(sum4.value); // 6
52
```
53

54
### useAverage
55

56
Reactively calculates the average (mean) of numbers from an array or multiple arguments.
57

58
```typescript { .api }
59
/**
60
 * Get the average of a set of numbers from an array
61
 * @param array - Array of reactive numbers or refs
62
 * @returns ComputedRef containing the average
63
 */
64
function useAverage(array: MaybeRefOrGetter<MaybeRefOrGetter<number>[]>): ComputedRef<number>;
65

66
/**
67
 * Get the average of a set of numbers from multiple arguments
68
 * @param args - Multiple reactive numbers or refs
69
 * @returns ComputedRef containing the average
70
 */
71
function useAverage(...args: MaybeRefOrGetter<number>[]): ComputedRef<number>;
72
```
73

74
**Usage Examples:**
75

76
```typescript
77
import { ref } from "vue";
78
import { useAverage } from "@vueuse/math";
79

80
// Array approach
81
const scores = ref([85, 92, 78, 94, 88]);
82
const average = useAverage(scores);
83
console.log(average.value); // 87.4
84

85
// Arguments approach
86
const test1 = ref(90);
87
const test2 = ref(85);
88
const test3 = ref(95);
89
const testAverage = useAverage(test1, test2, test3);
90
console.log(testAverage.value); // 90
91

92
// Updates reactively
93
scores.value.push(100);
94
console.log(average.value); // New average including 100
95
```
96

97
### useMax
98

99
Reactively finds the maximum value from numbers in an array or multiple arguments.
100

101
```typescript { .api }
102
/**
103
 * Get the maximum value from an array of numbers
104
 * @param array - Array of reactive numbers or refs
105
 * @returns ComputedRef containing the maximum value
106
 */
107
function useMax(array: MaybeRefOrGetter<MaybeRefOrGetter<number>[]>): ComputedRef<number>;
108

109
/**
110
 * Get the maximum value from multiple number arguments
111
 * @param args - Multiple reactive numbers or refs
112
 * @returns ComputedRef containing the maximum value
113
 */
114
function useMax(...args: MaybeRefOrGetter<number>[]): ComputedRef<number>;
115
```
116

117
**Usage Examples:**
118

119
```typescript
120
import { ref } from "vue";
121
import { useMax } from "@vueuse/math";
122

123
// Array approach
124
const temperatures = ref([22, 25, 19, 30, 28]);
125
const maxTemp = useMax(temperatures);
126
console.log(maxTemp.value); // 30
127

128
// Arguments approach
129
const price1 = ref(10.99);
130
const price2 = ref(8.99);
131
const price3 = ref(12.50);
132
const maxPrice = useMax(price1, price2, price3);
133
console.log(maxPrice.value); // 12.5
134

135
// With negative numbers
136
const values = ref([-5, -2, -10, -1]);
137
const max = useMax(values);
138
console.log(max.value); // -1
139
```
140

141
### useMin
142

143
Reactively finds the minimum value from numbers in an array or multiple arguments.
144

145
```typescript { .api }
146
/**
147
 * Get the minimum value from an array of numbers
148
 * @param array - Array of reactive numbers or refs
149
 * @returns ComputedRef containing the minimum value
150
 */
151
function useMin(array: MaybeRefOrGetter<MaybeRefOrGetter<number>[]>): ComputedRef<number>;
152

153
/**
154
 * Get the minimum value from multiple number arguments
155
 * @param args - Multiple reactive numbers or refs
156
 * @returns ComputedRef containing the minimum value
157
 */
158
function useMin(...args: MaybeRefOrGetter<number>[]): ComputedRef<number>;
159
```
160

161
**Usage Examples:**
162

163
```typescript
164
import { ref } from "vue";
165
import { useMin } from "@vueuse/math";
166

167
// Array approach
168
const expenses = ref([45.50, 12.30, 89.99, 23.40]);
169
const minExpense = useMin(expenses);
170
console.log(minExpense.value); // 12.3
171

172
// Arguments approach
173
const bid1 = ref(1000);
174
const bid2 = ref(950);
175
const bid3 = ref(1100);
176
const minBid = useMin(bid1, bid2, bid3);
177
console.log(minBid.value); // 950
178

179
// Empty array edge case
180
const empty = ref([]);
181
const minEmpty = useMin(empty);
182
console.log(minEmpty.value); // -Infinity (Math.min behavior)
183
```
184

185
## Utility Types
186

187
```typescript { .api }
188
/**
189
 * Type for functions accepting either spread args or single array arg
190
 */
191
type MaybeComputedRefArgs<T> = MaybeRefOrGetter<T>[] | [MaybeRefOrGetter<MaybeRefOrGetter<T>[]>];
192

193
/**
194
 * Utility to flatten and resolve MaybeComputedRefArgs to array of values
195
 * @param args - The arguments to flatten
196
 * @returns Flattened array of resolved values
197
 */
198
function toValueArgsFlat<T>(args: MaybeComputedRefArgs<T>): T[];
199
```
200

201
## Advanced Usage Patterns
202

203
### Combining Aggregation Functions
204

205
```typescript
206
import { ref, computed } from "vue";
207
import { useSum, useAverage, useMax, useMin } from "@vueuse/math";
208

209
const dataset = ref([10, 25, 15, 30, 20]);
210

211
const sum = useSum(dataset);
212
const average = useAverage(dataset);
213
const max = useMax(dataset);
214
const min = useMin(dataset);
215

216
// Computed statistics
217
const stats = computed(() => ({
218
  sum: sum.value,
219
  average: average.value,
220
  max: max.value,
221
  min: min.value,
222
  range: max.value - min.value,
223
  count: dataset.value.length
224
}));
225

226
console.log(stats.value);
227
// { sum: 100, average: 20, max: 30, min: 10, range: 20, count: 5 }
228
```
229

230
### Dynamic Data Updates
231

232
```typescript
233
import { ref, watch } from "vue";
234
import { useSum, useAverage } from "@vueuse/math";
235

236
const scores = ref([85, 90, 78]);
237
const sum = useSum(scores);
238
const average = useAverage(scores);
239

240
// Watch for changes
241
watch([sum, average], ([newSum, newAvg]) => {
242
  console.log(`Total: ${newSum}, Average: ${newAvg.toFixed(2)}`);
243
}, { immediate: true });
244

245
// Add new scores - watchers will fire automatically
246
scores.value.push(92, 88);
247
// Logs: "Total: 433, Average: 86.60"
248

249
// Modify existing score
250
scores.value[0] = 95;
251
// Logs: "Total: 443, Average: 88.60"
252
```