0
# Array Utilities
1

2
Reactive versions of native Array methods that work seamlessly with Vue's reactivity system. These utilities provide computed refs that automatically update when the source array changes.
3

4
## Capabilities
5

6
### useArrayFilter
7

8
Reactive version of Array.prototype.filter.
9

10
```typescript { .api }
11
/**
12
 * Reactive Array.filter
13
 * @param list - Source array (ref, getter, or value)
14
 * @param fn - Filter predicate function
15
 * @returns Computed ref with filtered array
16
 */
17
function useArrayFilter<T>(
18
  list: MaybeRefOrGetter<T[]>, 
19
  fn: (element: T, index: number, array: T[]) => boolean
20
): ComputedRef<T[]>;
21
```
22

23
**Usage Example:**
24

25
```typescript
26
import { useArrayFilter, ref } from "@vueuse/shared";
27

28
const numbers = ref([1, 2, 3, 4, 5, 6]);
29
const evenNumbers = useArrayFilter(numbers, (n) => n % 2 === 0);
30

31
console.log(evenNumbers.value); // [2, 4, 6]
32

33
numbers.value.push(8);
34
console.log(evenNumbers.value); // [2, 4, 6, 8]
35
```
36

37
### useArrayMap
38

39
Reactive version of Array.prototype.map.
40

41
```typescript { .api }
42
/**
43
 * Reactive Array.map
44
 * @param list - Source array (ref, getter, or value) 
45
 * @param fn - Map transformation function
46
 * @returns Computed ref with mapped array
47
 */
48
function useArrayMap<T, U>(
49
  list: MaybeRefOrGetter<T[]>, 
50
  fn: (element: T, index: number, array: T[]) => U
51
): ComputedRef<U[]>;
52
```
53

54
**Usage Example:**
55

56
```typescript
57
import { useArrayMap, ref } from "@vueuse/shared";
58

59
const numbers = ref([1, 2, 3]);
60
const doubled = useArrayMap(numbers, (n) => n * 2);
61

62
console.log(doubled.value); // [2, 4, 6]
63

64
const users = ref([{ name: 'John' }, { name: 'Jane' }]);
65
const names = useArrayMap(users, (user) => user.name);
66

67
console.log(names.value); // ['John', 'Jane']
68
```
69

70
### useArrayReduce
71

72
Reactive version of Array.prototype.reduce.
73

74
```typescript { .api }
75
/**
76
 * Reactive Array.reduce
77
 * @param list - Source array (ref, getter, or value)
78
 * @param reducer - Reducer function
79
 * @param initialValue - Initial accumulator value
80
 * @returns Computed ref with reduced value
81
 */
82
function useArrayReduce<T, U>(
83
  list: MaybeRefOrGetter<T[]>, 
84
  reducer: (previous: U, current: T, index: number, array: T[]) => U, 
85
  initialValue: MaybeRefOrGetter<U>
86
): ComputedRef<U>;
87
```
88

89
**Usage Example:**
90

91
```typescript
92
import { useArrayReduce, ref } from "@vueuse/shared";
93

94
const numbers = ref([1, 2, 3, 4, 5]);
95
const sum = useArrayReduce(numbers, (acc, curr) => acc + curr, 0);
96

97
console.log(sum.value); // 15
98

99
const items = ref([{ price: 10 }, { price: 20 }, { price: 30 }]);
100
const totalPrice = useArrayReduce(items, (acc, item) => acc + item.price, 0);
101

102
console.log(totalPrice.value); // 60
103
```
104

105
### useArrayFind
106

107
Reactive version of Array.prototype.find.
108

109
```typescript { .api }
110
/**
111
 * Reactive Array.find
112
 * @param list - Source array (ref, getter, or value)
113
 * @param fn - Find predicate function
114
 * @returns Computed ref with found element or undefined
115
 */
116
function useArrayFind<T>(
117
  list: MaybeRefOrGetter<T[]>, 
118
  fn: (element: T, index: number, array: T[]) => boolean
119
): ComputedRef<T | undefined>;
120
```
121

122
### useArrayFindIndex
123

124
Reactive version of Array.prototype.findIndex.
125

126
```typescript { .api }
127
/**
128
 * Reactive Array.findIndex
129
 * @param list - Source array (ref, getter, or value)
130
 * @param fn - Find predicate function
131
 * @returns Computed ref with found index or -1
132
 */
133
function useArrayFindIndex<T>(
134
  list: MaybeRefOrGetter<T[]>, 
135
  fn: (element: T, index: number, array: T[]) => boolean
136
): ComputedRef<number>;
137
```
138

139
### useArrayFindLast
140

141
Reactive version of Array.prototype.findLast.
142

143
```typescript { .api }
144
/**
145
 * Reactive Array.findLast
146
 * @param list - Source array (ref, getter, or value)
147
 * @param fn - Find predicate function
148
 * @returns Computed ref with last found element or undefined
149
 */
150
function useArrayFindLast<T>(
151
  list: MaybeRefOrGetter<T[]>, 
152
  fn: (element: T, index: number, array: T[]) => boolean
153
): ComputedRef<T | undefined>;
154
```
155

156
### useArrayEvery
157

158
Reactive version of Array.prototype.every.
159

160
```typescript { .api }
161
/**
162
 * Reactive Array.every
163
 * @param list - Source array (ref, getter, or value)
164
 * @param fn - Test predicate function
165
 * @returns Computed ref with boolean result
166
 */
167
function useArrayEvery<T>(
168
  list: MaybeRefOrGetter<T[]>, 
169
  fn: (element: T, index: number, array: T[]) => boolean
170
): ComputedRef<boolean>;
171
```
172

173
### useArraySome
174

175
Reactive version of Array.prototype.some.
176

177
```typescript { .api }
178
/**
179
 * Reactive Array.some
180
 * @param list - Source array (ref, getter, or value)
181
 * @param fn - Test predicate function
182
 * @returns Computed ref with boolean result
183
 */
184
function useArraySome<T>(
185
  list: MaybeRefOrGetter<T[]>, 
186
  fn: (element: T, index: number, array: T[]) => boolean
187
): ComputedRef<boolean>;
188
```
189

190
### useArrayIncludes
191

192
Reactive version of Array.prototype.includes.
193

194
```typescript { .api }
195
/**
196
 * Reactive Array.includes
197
 * @param list - Source array (ref, getter, or value)
198
 * @param value - Value to search for
199
 * @param fromIndex - Starting index for search
200
 * @returns Computed ref with boolean result
201
 */
202
function useArrayIncludes<T>(
203
  list: MaybeRefOrGetter<T[]>, 
204
  value: MaybeRefOrGetter<T>, 
205
  fromIndex?: MaybeRefOrGetter<number>
206
): ComputedRef<boolean>;
207
```
208

209
### useArrayJoin
210

211
Reactive version of Array.prototype.join.
212

213
```typescript { .api }
214
/**
215
 * Reactive Array.join
216
 * @param list - Source array (ref, getter, or value)
217
 * @param separator - Join separator string
218
 * @returns Computed ref with joined string
219
 */
220
function useArrayJoin<T>(
221
  list: MaybeRefOrGetter<T[]>, 
222
  separator?: MaybeRefOrGetter<string>
223
): ComputedRef<string>;
224
```
225

226
### useArrayUnique
227

228
Get unique values from an array.
229

230
```typescript { .api }
231
/**
232
 * Reactive unique array values
233
 * @param list - Source array (ref, getter, or value)
234
 * @param compareFn - Optional comparison function for custom uniqueness
235
 * @returns Computed ref with unique values
236
 */
237
function useArrayUnique<T>(
238
  list: MaybeRefOrGetter<T[]>, 
239
  compareFn?: (a: T, b: T) => boolean
240
): ComputedRef<T[]>;
241
```
242

243
**Usage Example:**
244

245
```typescript
246
import { useArrayUnique, ref } from "@vueuse/shared";
247

248
const numbers = ref([1, 2, 2, 3, 3, 4]);
249
const unique = useArrayUnique(numbers);
250

251
console.log(unique.value); // [1, 2, 3, 4]
252

253
// With custom comparison
254
const users = ref([
255
  { id: 1, name: 'John' },
256
  { id: 2, name: 'Jane' }, 
257
  { id: 1, name: 'John' }
258
]);
259

260
const uniqueUsers = useArrayUnique(users, (a, b) => a.id === b.id);
261
console.log(uniqueUsers.value); // [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]
262
```
263

264
### useArrayDifference
265

266
Get the difference between two arrays.
267

268
```typescript { .api }
269
/**
270
 * Reactive array difference
271
 * @param list - Source array (ref, getter, or value)
272
 * @param values - Values to exclude (ref, getter, or value)
273
 * @param key - Optional key for object comparison
274
 * @returns Computed ref with difference array
275
 */
276
function useArrayDifference<T>(
277
  list: MaybeRefOrGetter<T[]>, 
278
  values: MaybeRefOrGetter<T[]>, 
279
  key?: keyof T
280
): ComputedRef<T[]>;
281
```
282

283
**Usage Example:**
284

285
```typescript
286
import { useArrayDifference, ref } from "@vueuse/shared";
287

288
const list1 = ref([1, 2, 3, 4, 5]);
289
const list2 = ref([3, 4, 5, 6, 7]);
290

291
const difference = useArrayDifference(list1, list2);
292
console.log(difference.value); // [1, 2]
293

294
// With objects
295
const users1 = ref([
296
  { id: 1, name: 'John' },
297
  { id: 2, name: 'Jane' },
298
  { id: 3, name: 'Bob' }
299
]);
300

301
const users2 = ref([
302
  { id: 2, name: 'Jane' },
303
  { id: 3, name: 'Bob' }
304
]);
305

306
const userDiff = useArrayDifference(users1, users2, 'id');
307
console.log(userDiff.value); // [{ id: 1, name: 'John' }]
308
```