Presence List

Use it for lists that change while people watch: notifications, a queue, a filtered list, a table whose rows are added, removed or re-sorted. Each change happens where the eye can follow it. Don't use it when the whole list is replaced at once, like the next page of results. Key the list by page instead, or use Content Swap.

Installation

npm i @youj/motion

import { PresenceItem, PresenceList } from '@youj/motion'

For an app already set up with npx @youj/cli init, which installs the peers (@youj/core, @youj/motion, motion and Base UI) and wires the provider. New app? Start at Installation.

Usage

import { PresenceItem, PresenceList } from '@youj/motion'

export function Notifications({ items }: { items: Notification[] }) {
  return (
    <PresenceList className="flex flex-col gap-1">
      {items.map((item) => (
        <PresenceItem key={item.id} className="rounded-lg bg-surface px-3 py-2">
          {item.title}
        </PresenceItem>
      ))}
    </PresenceList>
  )
}

Every PresenceItem is a direct, keyed child of its PresenceList. The key is how a row is recognized as the same row after a change, so use a stable id, never the index.
as picks the elements: ul (the default), ol, tbody or div for the list, and li (the default), tr, div, article or section for items.
Items on the first render start settled. Pass initial to animate them in as well.

Examples

Table rows

Table rows rule out the usual tricks: an absolutely positioned <tr> loses table layout, and a row can't be clipped or collapsed by height. Presence List avoids both, and a table needs four rules of its own:

border-separate border-spacing-0, with dividers on the cells. border-collapse, Tailwind's default for tables, paints borders on the table grid, so they'd stay behind while rows move. A border-b on the row does nothing in separate mode.
A background on every row, such as bg-surface, so rows that cross during a re-sort cover each other cleanly.
Fixed column widths, with table-fixed or column sizing, so removing the widest row doesn't reflow every column mid-animation.
A keyed tbody for whole-page swaps. Key it by page for pagination, so a page change isn't twenty exits and twenty enters.

<table className="w-full table-fixed border-separate border-spacing-0">
  <thead>…</thead>
  <PresenceList as="tbody">
    {rows.map((row) => (
      <PresenceItem as="tr" key={row.id} className="bg-surface">
        <td className="border-b border-line [tr:last-child>&]:border-b-0">…</td>
      </PresenceItem>
    ))}
  </PresenceList>
</table>

Don't use it with a virtualizer such as TanStack Virtual, which positions rows itself.

PresenceList props
Prop	Type	Default
`as`	`'div' \| 'ol' \| 'tbody' \| 'ul'` The list element. default 'ul'	`'ul'`
`initial`	`boolean` Also animate the items present on first render. default false	`false`
`children`Required	`ReactNode` PresenceItems, keyed by a stable id.	–
Other props pass through: extends `HTMLAttributes<HTMLElement>`.

PresenceItem

PresenceItem props
Prop	Type	Default
`as`	`'div' \| 'section' \| 'article' \| 'li' \| 'tr'` The element to render. default 'li'	`'li'`
`children`	`ReactNode`	–
Other props pass through: extends `HTMLAttributes<HTMLElement>`.

MotionEnter, leave, move · reduced motion

Motion

Motion tokens
Moment	Tokens	Value
Enterfade and a 6px drop into the slot	`duration.baseease.enter` 220ms · cubic-bezier(0.16, 1, 0.3, 1)	220mscubic-bezier(0.16, 1, 0.3, 1)
Leavefade in place, keeping the space	`duration.fastease.exit` 140ms · cubic-bezier(0.4, 0, 1, 1)	140mscubic-bezier(0.4, 0, 1, 1)
Movemaking room, closing gaps, reordering	`spring.smooth` 0.36s, bounce 0	0.36s, bounce 0

Reduced motion

Items are added, removed and reordered in one frame, with no layout animation at all.

Reduced motion

Every change applies at once: new items appear in their slot, removed ones are gone, and reordered ones are in their new place. The list is the same as with motion. It just doesn't travel.

Accessibilityfocus, announcements