Animated List

A list that keeps a fixed number of rows on screen, animates new rows in, and visually demotes the rows above them. It reads like a live activity feed or a notification stack.

Two ideas do the work. Windowing: only the last maxVisible items render, so the list height stays fixed no matter how long the array gets. Receding: each row's opacity and scale are derived from its position — how far down the visible window it is — rather than from a single variant, so the top row is full size and each row below steps down by a fixed amount until it hits a floor.

maxVisible truncates by count, so items scroll off the top and are discarded from the DOM entirely. If you need them back, they are still in your array — nothing is removed. Use the exposed remove or the update:items event to actually delete them.

direction="down" renders newest-first, which is what makes the windowing feel like a feed. direction="up" appends at the bottom instead and reads like a chat log.

Usage

<template>
  <MAnimatedList
    v-model:items="items"
    :max-visible="4"
    animation="slide"
    direction="down"
    class="w-full max-w-md"
  >
    <template #default="{ item }">
      <div class="flex items-center gap-2 rounded-xl border border-default bg-default px-3 py-2">
        <UBadge
          :label="item.label"
          color="primary"
          variant="subtle"
        />
        <span class="truncate text-sm text-default">{{ item.text }}</span>
      </div>
    </template>
  </MAnimatedList>
</template>

<script setup lang="ts">
const items = ref([
  { id: 1, label: 'Deploy', text: 'Production build shipped' },
  { id: 2, label: 'Signup', text: 'New account created' },
  { id: 3, label: 'Payment', text: 'Invoice #1042 paid' },
  { id: 4, label: 'Alert', text: 'CPU usage above 80%' },
])
</script>

With no slot the component renders a UCard per row. If you set onItemClick, that fallback becomes clickable; otherwise it includes a remove button already wired to remove(row.sourceIndex).

The three exposed methods — add, remove and clear — all emit update:items rather than mutating anything, so v-model:items is the intended wiring and the array stays owned by the parent. In the example the Clear button goes through the exposed clear() rather than assigning items.value = [] directly; both work, and the first keeps the exit animation.

Examples

Live activity feed

<template>
  <div class="flex w-full max-w-md flex-col gap-4">
    <MAnimatedList
      ref="list"
      v-model:items="items"
      :max-visible="4"
      animation="slide"
      direction="down"
      class="w-full"
    >
      <template #default="{ item, index, remove }">
        <div class="flex items-center justify-between gap-3 rounded-xl border border-default bg-default px-3 py-2">
          <div class="flex min-w-0 items-center gap-2">
            <UBadge
              :label="item.label"
              color="primary"
              variant="subtle"
            />
            <span class="truncate text-sm text-default">{{ item.text }}</span>
          </div>
          <UButton
            icon="i-lucide-x"
            color="neutral"
            variant="ghost"
            size="xs"
            :aria-label="`Dismiss ${item.text}`"
            @click.stop="remove(index)"
          />
        </div>
      </template>
    </MAnimatedList>

    <div class="flex items-center gap-3">
      <UButton
        label="Add alert"
        icon="i-lucide-bell"
        variant="outline"
        class="justify-center"
        @click="add"
      />
      <UButton
        label="Clear"
        icon="i-lucide-trash-2"
        color="neutral"
        variant="ghost"
        class="justify-center"
        @click="clear"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
interface Alert {
  id: number
  label: string
  text: string
}

let counter = 4

const list = ref<{ clear: () => void } | null>(null)
const items = ref<Alert[]>([
  { id: 1, label: 'Deploy', text: 'Deploy finished for web' },
  { id: 2, label: 'Signup', text: 'New account created' },
  { id: 3, label: 'Payment', text: 'Invoice #1042 paid' },
  { id: 4, label: 'Alert', text: 'CPU usage above 80%' },
])

function add() {
  counter += 1
  items.value = [
    ...items.value,
    { id: counter, label: 'Deploy', text: `Event #${counter} received` },
  ]
}

function clear() {
  list.value?.clear()
}
</script>

Customize

Props

Events

Slots

UI

This component's theme exposes the slots below. Override any of them per instance with the ui prop, or app-wide under ui.animatedList in app.config.ts.

Accessibility

The root is a real <ul aria-live="polite"> and each row is a <li>, so the structure is announced correctly. inheritAttrs is disabled and $attrs are re-bound manually, so class, aria-* and listeners land on the <ul> as you'd expect.

The aria-live region is a problem on a fast feed. Any add, remove or recede re-inserts elements inside a polite live region, and screen readers will read the new row out — which is usually what you want, but it means the region stays "noisy" for as long as the list is changing. If your rows are not announcements, set aria-live="off" yourself (or manage focus in a role="log" region) rather than leaving the default on.

The list does not move focus, and it should not: rows are not interactive unless you make them so. If a row contains a button, note that rows are removed from the DOM as they age out of the window — moving focus to a button that is about to be unmounted sends focus back to body.

Reduced motion is fully respected. useReducedMotion() short-circuits every variant: entries appear at their final values, the stagger delay becomes 0, and exits fade with duration: 0. The list still updates, it just doesn't travel.

Performance

• Rendering is bounded by maxVisible, so the DOM size does not grow with the array. A 10,000-item array costs the same as a 5-item one.
• Every row sets layout, so Motion measures positions before and after each change. That is a forced reflow per update and is the dominant cost — it is what makes the neighbouring rows slide instead of jump.
• Stagger is capped at 0.3s (MAX_STAGGER_DELAY), so a large maxVisible cannot stretch a single update into a long, janky sequence.
• Recede clamps at MIN_RECEDE_OPACITY / MIN_RECEDE_SCALE, so old rows never become invisible or invert — you never lose a row to rounding.
• AnimatePresence uses mode="popLayout", which removes a leaving row from flow immediately so the remaining rows start moving straight away rather than waiting for the exit to finish.
• The feed timer is a single setTimeout that reschedules itself, and it is cleared and re-armed by a watcher on feed, feedInterval, items.length and the pause state — so changing any of them mid-flight cannot leave a stale timer running.