Motion

How a component moves belongs to its family, like its colours. A component never plays an animation of its own: it says what is happening, and the family's CSS decides how it looks — or that nothing moves. Your app can still take any motion back with a Svelte transition.

Coming, going, moving

When an element appears, leaves or changes place, the component marks it, then waits exactly as long as the family's CSS on it lasts, read from the computed style. A family that draws nothing makes it instant.

data-motion="enter"
Just inserted, while the family's animation runs. A new element has nothing to transition from: use @keyframes or @starting-style.
data-motion="leave"
Going: it stays in the DOM until its transitions and animations have run.
data-motion="move"
Changed place in a list. --motion-dx / --motion-dy hold where it came from.
--motion-w / --motion-h
Its size as it enters or leaves, for a family that opens or collapses it.
/* In a family, or in your own stylesheet */
@media (prefers-reduced-motion: no-preference) {
  .toast-item[data-motion='enter'] { animation: toast-in 0.2s ease-out; }
  .toast-item[data-motion='leave'] { opacity: 0; transition: opacity 0.15s; }
  .toast-item[data-motion='move']  { animation: toast-move 0.2s ease; }
}
@keyframes toast-move {
  from { translate: var(--motion-dx) var(--motion-dy); }
}

A family writes its motion under prefers-reduced-motion: no-preference, and is free to draw none: the DOM tab of a component page says what it marks, whether the family picked draws it or not.

Continuous state is written, not played

An indicator that follows a selection — tabs, a switch — gets its place in custom properties, measured after the change. The family decides whether it slides.

.tabs-indicator {
  left: var(--tabs-x);
  width: var(--tabs-w);
  transition: left 0.25s, width 0.25s;   /* or none: it jumps */
}

Your own Svelte transition

Every component that makes something come and go takes a transition prop: Dialog, Dropdown, Toast, Alert, DataControl, Combobox and Select (their list), ChipsInput (a chip), Kanban (a card), FileExplorer (a branch of the tree). Toast and ChipsInput take animate for the move of the others. A family may not draw every one of these yet: then it is instant, and the prop is how you give it a motion.

  • Left out: the family plays it.
  • false: nothing does, it is instant.
  • A Svelte transition — fly, { fn: fly, params }, { in: fly, out: fade } — plays instead. The element is then not marked, so the family's CSS stays out of it: the two never play at once.
<script>
  import { fly, fade } from 'svelte/transition';
  import { flip } from 'svelte/animate';
</script>

<Dialog transition={fly}>…</Dialog>
<Dropdown transition={{ fn: fly, params: { y: -8, duration: 150 } }}>…</Dropdown>
<Toast transition={{ in: fly, out: fade }} animate={flip} />
<Alert dismissible transition={false}>Instant</Alert>

From one list to another: crossfade

An item that changes list is not moved by Svelte: it leaves one list and a new element enters the other. Svelte's crossfade() pairs the two by a key and makes the item fly across. Its pair [send, receive] is a transition as is, and the components with keyed items — Kanban, ChipsInput, Toast — hand it each item's key. Give the list its key ("id"), or items are paired by position.

<script>
  import { crossfade } from 'svelte/transition';
  import { flip } from 'svelte/animate';
  const pair = crossfade({ duration: 300 });   /* [send, receive] */
</script>

<!-- A card moved to another column flies there, the others slide -->
<Kanban items={tasks} key="id" columnOf={(t) => t.status} transition={pair} animate={flip}>…</Kanban>

<!-- Shared between two components, an item flies from one to the other -->
<ChipsInput bind:values={picked} transition={pair} />
<ChipsInput bind:values={left} transition={pair} />

Moves the component measures (FLIP)

The family's CSS cannot know that an item changed list: it sees an element leave and another enter. And Svelte's animate: only moves the sole child of a keyed block. Where neither reaches, a component can measure its moves itself: where each keyed element stands before a change, and after. An element that stands elsewhere is marked data-motion="move" from where it stood — the same phase as any other move, drawn by the same CSS — and an item that changed list neither leaves nor enters: its old element goes at once, the new one arrives as a move.

Kanban does it for its cards, within a column and from one column to another. It is a mechanism ready for the families: none draws move on .kanban-item yet, so the cards still jump until one does — or until your stylesheet does.

@media (prefers-reduced-motion: no-preference) {
  .kanban-item[data-motion='move'] { animation: kanban-move 0.25s ease; }
}
@keyframes kanban-move {
  from { translate: var(--motion-dx) var(--motion-dy); }
}

The same tool, Reflow, is exported for your own lists. Measure in $effect.pre, play in $effect, and let reflow.motion() tell an item that only moves from one that comes or goes.

<script>
  import { motion, Reflow } from '@sepale/components';

  let { cards, columns } = $props();
  let board = $state();
  const reflow = new Reflow(() => board, 'cardKey');   /* reads data-card-key */
  let ids = $derived(new Set(cards.map((c) => c.id)));  /* the keys after the change */

  $effect.pre(() => { void cards; reflow.measure(); });   /* before the DOM changes */
  $effect(() => { void cards; reflow.play(); });          /* after: marks the moves */
</script>

<div bind:this={board}>
  {#each columns as column (column.id)}
    {#each cards.filter((c) => c.column === column.id) as card (card.id)}
      <article
        data-card-key={card.id}
        in:motion={reflow.motion(card.id, undefined, ids.has(card.id))}
        out:motion={reflow.motion(card.id, undefined, ids.has(card.id))}
      >…</article>
    {/each}
  {/each}
</div>

What is not a coming and going

A hover, a press, a focus, a colour that changes: the element stays, only its state changes. That is a CSS transition on :hover or :active, the family's like the rest of its look, and overridden in CSS. A Svelte transition only plays when an element enters or leaves the DOM, or moves in a keyed list.

The same contract for your elements

motion and moved are exported: your own elements can leave their motion to the family, or to your stylesheet, the same way. settle(node, done) waits for the motion of a change of state.

<script>
  import { motion, moved } from '@sepale/components';
</script>

{#each items as item (item.id)}
  <div class="card" in:motion out:motion animate:moved>…</div>
{/each}