use-array

Reactive Array.prototype.filter.

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 { useArrayFilter, useArrayMap, useArrayFind, useArrayReduce, useArraySome, useArrayEvery, useArrayUnique } from "@vizejs/composable/use-array";

Try it

Check off a packing list

Derive filtered and summary views from a reactive list without copying it into extra state.

Open the interactive example

What to observe: Passport starts packed, so the message lists Charger and Umbrella. Check both to see Everything is packed; uncheck one to bring it back.

useArrayFilter and useArrayEvery return computed refs over the source list. Nested changes such as item.packed are tracked because the list is a deep ref.

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 { ref } from "vue";
import { useArrayEvery, useArrayFilter } from "@vizejs/composable/use-array";

const items = ref([
  { id: 1, label: "Passport", packed: true },
  { id: 2, label: "Charger", packed: false },
  { id: 3, label: "Umbrella", packed: false },
]);
const remaining = useArrayFilter(items, (item) => !item.packed);
const allPacked = useArrayEvery(items, (item) => item.packed);
</script>

<template>
  <div class="composable-example">
    <p>Check off a packing list and see what is still missing.</p>
    <ul aria-label="Packing list">
      <li v-for="item in items" :key="item.id">
        <label><input v-model="item.packed" type="checkbox" /> {{ item.label }}</label>
      </li>
    </ul>
    <output aria-live="polite">{{
      allPacked
        ? "Everything is packed."
        : `Still to pack: ${remaining.map((item) => item.label).join(", ")}`
    }}</output>
  </div>
</template>

Runtime contract

API

useArrayFilter

Reactive Array.prototype.filter. A type-guard predicate narrows the element type.

function useArrayFilter<Item, Narrowed extends Item>( list: MaybeRefOrGetter<readonly Item[]>, predicate: (item: Item, index: number, array: readonly Item[]) => item is Narrowed, ): ComputedRef<Narrowed[]>

const active = useArrayFilter(users, (user) => user.active);

useArrayFilter

function useArrayFilter<Item>( list: MaybeRefOrGetter<readonly Item[]>, predicate: ArrayCallback<Item, boolean>, ): ComputedRef<Item[]>

useArrayFilter

function useArrayFilter<Item>( list: MaybeRefOrGetter<readonly Item[]>, predicate: ArrayCallback<Item, boolean>, ): ComputedRef<Item[]>

useArrayMap

Reactive Array.prototype.map.

function useArrayMap<Item, Mapped>( list: MaybeRefOrGetter<readonly Item[]>, mapper: ArrayCallback<Item, Mapped>, ): ComputedRef<Mapped[]>

const names = useArrayMap(users, (user) => user.name);

useArrayFind

Reactive Array.prototype.find. A type-guard predicate narrows the result.

function useArrayFind<Item, Narrowed extends Item>( list: MaybeRefOrGetter<readonly Item[]>, predicate: (item: Item, index: number, array: readonly Item[]) => item is Narrowed, ): ComputedRef<Narrowed | undefined>

const admin = useArrayFind(users, (user) => user.role === "admin");

useArrayFind

function useArrayFind<Item>( list: MaybeRefOrGetter<readonly Item[]>, predicate: ArrayCallback<Item, boolean>, ): ComputedRef<Item | undefined>

useArrayFind

function useArrayFind<Item>( list: MaybeRefOrGetter<readonly Item[]>, predicate: ArrayCallback<Item, boolean>, ): ComputedRef<Item | undefined>

useArrayReduce

Reactive Array.prototype.reduce. With an initial value the result has the accumulator type. Without one, the first item seeds the accumulator and an empty array yields undefined (instead of throwing like reduce).

function useArrayReduce<Item, Accumulator>( list: MaybeRefOrGetter<readonly Item[]>, reducer: ( accumulator: Accumulator, item: Item, index: number, array: readonly Item[], ) => Accumulator, initial: MaybeRefOrGetter<Accumulator>, ): ComputedRef<Accumulator>

const total = useArrayReduce(cart, (sum, line) => sum + line.price, 0);

useArrayReduce

function useArrayReduce<Item>( list: MaybeRefOrGetter<readonly Item[]>, reducer: (accumulator: Item, item: Item, index: number, array: readonly Item[]) => Item, ): ComputedRef<Item | undefined>

useArrayReduce

function useArrayReduce<Item>( list: MaybeRefOrGetter<readonly Item[]>, reducer: (accumulator: unknown, item: Item, index: number, array: readonly Item[]) => unknown, ...initial: readonly [] | readonly [MaybeRefOrGetter<unknown>] ): ComputedRef<unknown>

useArraySome

Reactive Array.prototype.some.

function useArraySome<Item>( list: MaybeRefOrGetter<readonly Item[]>, predicate: ArrayCallback<Item, boolean>, ): ComputedRef<boolean>

const hasErrors = useArraySome(fields, (field) => field.error !== null);

useArrayEvery

Reactive Array.prototype.every.

function useArrayEvery<Item>( list: MaybeRefOrGetter<readonly Item[]>, predicate: ArrayCallback<Item, boolean>, ): ComputedRef<boolean>

const allDone = useArrayEvery(tasks, (task) => task.done);

useArrayUnique

Reactive de-duplication that keeps the first occurrence of each item. Without isSame, items are compared with SameValueZero (like Set) in linear time; with it, pairwise in quadratic time.

function useArrayUnique<Item>( list: MaybeRefOrGetter<readonly Item[]>, isSame?: (left: Item, right: Item) => boolean, ): ComputedRef<Item[]>

const tags = useArrayUnique(allTags);
const people = useArrayUnique(rows, (left, right) => left.id === right.id);