MotionSwap

Content that cross-fades while its size follows.

WebReact NativeContent and size

Try it

Preparing the example…

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

App.jsx

import { useEffect, useState } from 'react';
import { MotionSwap, motionTokens } from '@kkwaenggwari/animated-chorus';
import './styles.css';

function Check() {
  return (
    <svg width="16" height="16" viewBox="0 0 16 16">
      <path d="m3 8.5 3 3 7-7" fill="none" stroke="currentColor" strokeWidth="2" />
    </svg>
  );
}

export default function App({ effect = 'up', align = 'center', spring = 'default' }) {
  const [status, setStatus] = useState('idle');
  const [loaded, setLoaded] = useState(true);
  // "default" is not a preset: undefined keeps the component's own motion.
  const transition = motionTokens.spring[spring];

  useEffect(() => {
    if (status === 'idle') return;
    const next = status === 'saving' ? 'saved' : 'idle';
    const timer = setTimeout(() => setStatus(next), status === 'saving' ? 1100 : 1600);
    return () => clearTimeout(timer);
  }, [status]);

  useEffect(() => {
    if (loaded) return;
    const timer = setTimeout(() => setLoaded(true), 1200);
    return () => clearTimeout(timer);
  }, [loaded]);

  return (
    <div className="stage">
      <button className={`save ${status}`} onClick={() => setStatus('saving')}>
        <MotionSwap value={status} effect={effect} align={align} transition={transition}>
          {status === 'idle' && 'Save changes'}
          {status === 'saving' && 'Saving…'}
          {status === 'saved' && (
            <>
              <Check /> Saved
            </>
          )}
        </MotionSwap>
      </button>

      <MotionSwap
        as="div"
        inline={false}
        value={loaded ? 'profile' : 'loading'}
        effect={effect}
        transition={transition}
        className="profile"
      >
        {loaded ? (
          <div className="person">
            <span className="avatar">MK</span>
            <div>
              <strong>Min-ji Kim</strong>
              <p>Design engineer. Builds the motion system and the component docs.</p>
            </div>
          </div>
        ) : (
          <div className="skeleton">
            <span />
            <span />
          </div>
        )}
      </MotionSwap>
      <button className="reload" onClick={() => setLoaded(false)}>
        Reload profile
      </button>
    </div>
  );
}

styles.css

.stage {
  display: grid;
  justify-items: center;
  gap: 18px;
  max-width: 460px;
  margin: 0 auto;
  padding: 32px 20px;
}

.save {
  min-height: 48px;
  padding: 0 22px;
  border: 0;
  border-radius: 999px;
  background: #176b52;
  color: #fff;
  font:
    650 16px system-ui,
    sans-serif;
  cursor: pointer;
  transition: background-color 0.2s;
}

.save.saving {
  background: #2e8f6d;
}

.save.saved {
  background: #0e2e24;
}

.save svg {
  vertical-align: -2px;
}

.profile {
  width: 100%;
  border: 1px solid #cfe8dc;
  border-radius: 16px;
  background: #fff;
}

.person {
  display: flex;
  gap: 14px;
  padding: 18px;
}

.person p {
  margin: 4px 0 0;
  color: #5b616b;
}

.avatar {
  display: grid;
  flex: none;
  place-items: center;
  width: 48px;
  height: 48px;
  border-radius: 50%;
  background: #eaf6f0;
  color: #176b52;
  font-weight: 700;
}

.skeleton {
  display: grid;
  gap: 10px;
  padding: 22px 18px;
}

.skeleton span {
  height: 12px;
  border-radius: 6px;
  background: #eaf6f0;
}

.skeleton span:last-child {
  width: 60%;
}

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

Shortest usage

SaveButton.jsx

<button onClick={save}>
  <MotionSwap value={status} effect="up">
    {status === 'saving' ? 'Saving…' : status === 'saved' ? 'Saved' : 'Save'}
  </MotionSwap>
</button>;

What it handles for you

The element resizes from its size on screen to the new content's natural size, so buttons never jump.
The old content fades out where it was while the new content fades in; neither reflows during the swap.
Changing back in the middle of a swap continues from what is on screen instead of stacking copies.
Plain text children are their own value; pass value for anything else.

Use it for

Save, then Saving…, then Saved.
A skeleton that becomes a profile card.
A play button that becomes pause.

Props

Prop	Type	Default	Description
`value`	`unknown`		Identity of the content; a new value swaps. Plain text children are their own identity.
`children`	`ReactNode`		The content.
`as`	`element`	`'span'`	The element to render.
`inline`	`boolean`	`as === 'span'`	`true` sizes to the content (labels, icons); `false` fills the parent width and animates height.
`align`	`'start' \| 'center' \| 'end'`	`'center'`	Where the content sits while the size changes.
`effect`	`'fade' \| 'up' \| 'down' \| 'scale'`	`'fade'`	How content enters and leaves: `up` rises, `down` falls, `scale` grows.
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.
`onMotionComplete`	`(value) => void`		Runs when the motion settles.

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

Web and React Native

inline (the default when rendered as a span) animates width and height; inline={false} fills the parent width and animates height.

On React Native, inline swaps measure the new content on one line; use inline={false} for content that wraps.

Used in these examples

Chat answerSuggestions that fold away, an answer that streams at a steady pace and a status line that swaps.MotionStreamMotionListMotionSwapMotionHeight