MotionList

A list from data that animates only what changed.

WebReact NativeLists

Try it

Preparing the example…

JavaScript is off. The code below is the complete example.

App.jsx

import { useState } from 'react';
import { MotionList } from '@kkwaenggwari/animated-chorus';
import './styles.css';

const ideas = [
  'Plan the launch',
  'Write release notes',
  'Record a demo',
  'Update the docs',
  'Reply to issues',
  'Tag the release',
];

export default function App({ effect = 'rise', stagger = 40, distance = 18 }) {
  const [tasks, setTasks] = useState([
    { id: 1, title: 'Review the design' },
    { id: 2, title: 'Fix the flaky test' },
    { id: 3, title: 'Ship the changelog' },
  ]);
  const [next, setNext] = useState(4);

  const add = () => {
    setTasks([{ id: next, title: ideas[next % ideas.length] }, ...tasks]);
    setNext(next + 1);
  };
  const remove = (id) => setTasks(tasks.filter((task) => task.id !== id));
  const shuffle = () => setTasks([...tasks.slice(1), tasks[0]].filter(Boolean));
  const sort = () => setTasks([...tasks].sort((a, b) => a.title.localeCompare(b.title)));

  return (
    <div className="stage">
      <div className="buttons">
        <button className="primary" onClick={add}>
          Add task
        </button>
        <button onClick={shuffle}>Move first to end</button>
        <button onClick={sort}>Sort A–Z</button>
      </div>
      <MotionList
        as="ul"
        className="tasks"
        items={tasks}
        effect={effect}
        stagger={stagger}
        distance={distance}
        renderItem={(task) => (
          <div className="task">
            <span>{task.title}</span>
            <button onClick={() => remove(task.id)}>Done</button>
          </div>
        )}
      />
    </div>
  );
}

styles.css

.stage {
  display: grid;
  gap: 16px;
  max-width: 520px;
  min-height: 360px;
  margin: 0 auto;
  padding: 24px 20px;
  align-content: start;
}

.buttons {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}

.buttons button {
  min-height: 44px;
  padding: 0 16px;
  border: 1px solid #cfe8dc;
  border-radius: 999px;
  background: #fff;
  font:
    600 14px system-ui,
    sans-serif;
  cursor: pointer;
}

.buttons .primary {
  border-color: #176b52;
  background: #176b52;
  color: #fff;
}

.tasks {
  display: grid;
  gap: 8px;
  margin: 0;
  padding: 0;
  list-style: none;
}

.task {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
  padding: 10px 10px 10px 16px;
  border: 1px solid #cfe8dc;
  border-radius: 12px;
  background: #fff;
}

.task button {
  min-height: 36px;
  padding: 0 14px;
  border: 0;
  border-radius: 999px;
  background: #eaf6f0;
  color: #176b52;
  font:
    650 13px system-ui,
    sans-serif;
  cursor: pointer;
}

Shortest usage

Todos.jsx

<MotionList as="ul" items={todos} renderItem={(todo) => <TodoRow todo={todo} />} />;

What it handles for you

New items enter with a bounded stagger while untouched items stay still.
Removed items leave the flow and animate out where they were while the rest slide into the gap.
Reordered items glide to their new positions.
Moves interrupted by another change keep their velocity.
present={false} animates every item out, and playKey replays the entrance.

Use it for

A todo list.
Filtered search results.
A shopping cart.

Props

Prop	Type	Default	Description
`items`	`readonly T[]`	`—`required	Your data array.
`getKey`	`(item) => string \| number`	`item.id`	Returns a unique, stable key for an item. Defaults to `item.id`, or the item itself for strings and numbers.
`renderItem`	`(item, index) => ReactNode`	`item.label`	Draws an item.
`as`	`element`	`'div'`	The element to render.
`itemAs`	`element`	`'li' \| 'div'`	The element for each item.
`itemClassName`	`string`		Class for each item element; `itemStyle` sets its inline style.
`effect`	`'rise' \| 'fade' \| 'scale' \| 'slide'`	`'rise'`	How items enter and leave.
`distance`	`number`	`16`	Travel of `rise` and `slide` in pixels.
`stagger`	`number`	`40`	Milliseconds between entering items.
`order`	`'forward' \| 'reverse'`	`'forward'`	Direction of the stagger.
`present`	`boolean`	`true`	`false` animates every item out while keeping the layout; `true` brings them back.
`initial`	`boolean`	`true`	Play the entrance when the list mounts.
`playKey`	`string \| number`		Changing it replays the entrance.
`transition`	`Transition`	`spring`	Transition for entering and leaving items.
`layoutTransition`	`Transition`	`spring`	Transition for items gliding to new positions.

Other props go to the rendered element, so className, style and event handlers work as usual.

Web and React Native

Each item gets a wrapper element (li inside ul or ol, otherwise div; itemAs changes it) styled with itemClassName.

Keys must be unique. Wrap the list in MotionHeight to animate its total height as well.