React · React Native · 16 個元件

難做的互動，已經完成。

Animated Chorus 是一組動態元件，專為那些很難手寫到位的互動而生：滾動的數字、串流文字、尺寸會跟著變的切換、底部面板、翻頁器、滑動操作，以及只為變動項目加上動畫的清單。一個標籤加上你的資料，不需要 Provider，也不需要設定。

開始使用瀏覽元件

安裝

npm install @kkwaenggwari/animated-chorus

本次建置的實測數據

Chrome，2026-09-28。所有條件與樣本都在效能指南中。測量方法

28.0KBKB gzip，全部 16 個匯出
整個 Web 進入點，已壓縮。唯一的 peer 相依是 React。
0動畫進行時的 JS 影格回呼
數字、高度與醒目標示同時變化：全部 12 個動畫都由瀏覽器播放。
1每次值變化的 React commit 次數
MotionNumber 在值改變時渲染，滾動過程中從不渲染。
11串流 3000 個字元時的 React commit 次數
MotionStream 直接附加字元，每秒只併入 React 幾次。

01最簡單

一個標籤加上你的資料

每個元件都能獨立運作：不需要 Provider、包裝元件或初始化呼叫。集合類元件接收 items 與 renderItem，版面、文字與樣式都歸你所有。

匯入一個元件、傳一個值，整合就完成了。
清單、分頁標籤與翻頁器讀取你的陣列；key 預設為 item.id。
文字始終是真正的文字：會換行、隨字型縮放，也能被選取。

```
<MotionNumber value={total} />;
```

<MotionSwap value={status}>{label}</MotionSwap>;

<MotionHeight open={open}>{details}</MotionHeight>;

<MotionHighlight items={tabs} value={tab} onValueChange={setTab} />;

<MotionList items={tasks} renderItem={(task) => task.title} />;

```
<ProgressRing value={progress} />;
```

六個即時運作的元件，以及各自背後的那一行程式碼。

正在準備範例…

JavaScript 已關閉。下方的程式碼就是完整的範例。

App.jsx

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

const plans = [
  { id: 'starter', label: 'Starter', price: 0, points: ['1 project', 'Community support'] },
  {
    id: 'team',
    label: 'Team',
    price: 24,
    points: ['10 projects', 'Shared workspaces', 'Priority support'],
  },
  {
    id: 'scale',
    label: 'Scale',
    price: 196,
    points: ['Unlimited projects', 'Single sign-on', 'Audit log', 'Dedicated support'],
  },
];

export default function App({ hover = true, effect = 'up', spring = 'default' }) {
  const [plan, setPlan] = useState('team');
  const current = plans.find((item) => item.id === plan);
  // "default" is not a preset: undefined keeps the component's own motion.
  const transition = motionTokens.spring[spring];

  return (
    <div className="card">
      <MotionHighlight
        items={plans}
        value={plan}
        onValueChange={setPlan}
        hover={hover}
        transition={transition}
        className="tabs"
        itemClassName="tab"
        highlightClassName="tab-highlight"
        renderItem={(item, { selected }) => (
          <span className={selected ? 'tab-label on' : 'tab-label'}>{item.label}</span>
        )}
      />
      <p className="price">
        <MotionNumber value={current.price} prefix="$" transition={transition} />
        <span className="per">per month</span>
      </p>
      <MotionSwap as="div" inline={false} value={plan} effect={effect} transition={transition}>
        <ul className="points">
          {current.points.map((point) => (
            <li key={point}>{point}</li>
          ))}
        </ul>
      </MotionSwap>
    </div>
  );
}

styles.css

.card {
  display: grid;
  gap: 18px;
  max-width: 420px;
  margin: 24px auto;
  padding: 22px;
  border: 1px solid #cfe8dc;
  border-radius: 18px;
  background: #fff;
}

.tabs {
  display: flex;
  gap: 2px;
  padding: 4px;
  border-radius: 999px;
  background: #eaf6f0;
}

.tab {
  flex: 1;
  min-height: 40px;
  border: 0;
  border-radius: 999px;
  background: none;
  font:
    650 15px system-ui,
    sans-serif;
  color: #0e2e24;
  cursor: pointer;
}

.tab-highlight {
  border-radius: 999px;
  background: #fff;
  box-shadow: 0 0 0 1px #cfe8dc;
}

.tab-label {
  color: #5b616b;
  transition: color 0.2s;
}

.tab-label.on {
  color: #176b52;
}

.price {
  display: flex;
  align-items: baseline;
  gap: 8px;
  margin: 0;
  font:
    800 44px/1 system-ui,
    sans-serif;
  font-variant-numeric: tabular-nums;
  color: #0e2e24;
}

.price .per {
  font-size: 15px;
  font-weight: 500;
  color: #5b616b;
}

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

.points li {
  padding: 12px 14px;
  border-radius: 12px;
  background: #f4faf7;
  color: #16181d;
}

02最快

交給瀏覽器播放，React 保持靜止。

在 Web 上不必載入動畫函式庫：元件把動態交給 Web Animations API，所以滾動的數字或改變尺寸的面板在移動時不耗費每一格的 JavaScript，也不觸發 React 渲染。

12 個動畫同時執行時，JS 影格回呼為 0 次。
每次值變化只有一次 React commit，而不是每一格一次。
串流文字：3000 個字元只有 11 次 React commit。下方的範例會計算自己的渲染次數。

正在準備範例…

JavaScript 已關閉。下方的程式碼就是完整的範例。

App.jsx

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

const answer =
  'Motion helps people follow change. When a total updates, a rolling number shows which way it moved. ' +
  'When a panel opens, the height that follows its content keeps the reader in place. ' +
  'When an answer arrives in bursts, a steady reveal turns the bursts into reading: nothing waits for the ' +
  'next packet, and nothing is dumped at once. The pace speeds up only when a backlog builds, so the text ' +
  'never falls far behind what the server has already sent.';

// Network-like bursts: long pauses, then a lot of text at once.
const pauses = [300, 1100, 250, 1500, 400, 900];

export default function App({ speed = 90, catchUp = 900, chunk = 160, effect = 'fade' }) {
  const [received, setReceived] = useState(0);
  const [chunks, setChunks] = useState(0);
  const renders = useRef(0);
  renders.current += 1;

  useEffect(() => {
    if (received >= answer.length) return;
    const timer = setTimeout(
      () => {
        setReceived((current) => Math.min(answer.length, current + chunk));
        setChunks((count) => count + 1);
      },
      pauses[chunks % pauses.length],
    );
    return () => clearTimeout(timer);
  }, [received, chunks, chunk]);

  const askAgain = () => {
    setReceived(0);
    setChunks(0);
  };

  return (
    <div className="chat">
      <p className="question">Why does motion help an interface?</p>
      <p className="answer">
        <MotionStream
          text={answer.slice(0, received)}
          speed={speed}
          catchUp={catchUp}
          effect={effect}
        />
      </p>
      <footer>
        <output>
          {chunks} chunks · App rendered {renders.current} times
        </output>
        <button onClick={askAgain}>Ask again</button>
      </footer>
    </div>
  );
}

styles.css

.chat {
  display: grid;
  gap: 16px;
  max-width: 620px;
  margin: 0 auto;
  padding: 24px 20px;
}

.question {
  justify-self: end;
  max-width: 80%;
  margin: 0;
  padding: 10px 16px;
  border-radius: 18px 18px 4px 18px;
  background: #176b52;
  color: #fff;
}

.answer {
  min-height: 180px;
  margin: 0;
  padding: 16px 18px;
  border: 1px solid #cfe8dc;
  border-radius: 18px 18px 18px 4px;
  background: #fff;
  color: #16181d;
  line-height: 1.65;
}

footer {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  justify-content: space-between;
  gap: 10px;
}

output {
  font:
    600 13px ui-monospace,
    Consolas,
    monospace;
  color: #176b52;
}

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

03最穩定

隨時中斷，從不跳動。

每個新值都從畫面上的當下狀態開始，彈簧會保留速度，所以快速連點、資料一次湧入與反向操作看起來都是刻意的。動態結束後，不會留下任何還在執行的東西。

數字從不斷開：保留的位數會一邊滾動一邊滑動。
間隔 5 ms 連續給 200 個新值：之後只剩 0 個動畫，最後的文字完全正確。
在 React StrictMode 下也安全。React Native 應用程式在背景時，動態會直接落到結束狀態。

正在準備範例…

JavaScript 已關閉。下方的程式碼就是完整的範例。

App.jsx

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

const burst = [12, 37, 85, 140, 9, 260, 48, 530, 21, 1100, 75, 2300];

export default function App({ mode = 'roll', direction = 'auto', spring = 'default' }) {
  const [value, setValue] = useState(1280);
  const [changes, setChanges] = useState(0);
  const [bursting, setBursting] = useState(false);

  const change = (next) => {
    setValue(next);
    setChanges((count) => count + 1);
  };

  // Twelve rising values, 90 ms apart, like a live counter: each arrives mid-motion.
  useEffect(() => {
    if (!bursting) return;
    let step = 0;
    const timer = setInterval(() => {
      const delta = burst[step];
      setValue((current) => Math.max(0, current + delta));
      setChanges((count) => count + 1);
      step += 1;
      if (step === burst.length) {
        clearInterval(timer);
        setBursting(false);
      }
    }, 90);
    return () => clearInterval(timer);
  }, [bursting]);

  return (
    <div className="counter">
      <MotionNumber
        className="value"
        value={value}
        intl
        locale="en-US"
        mode={mode}
        direction={direction}
        transition={motionTokens.spring[spring]}
      />
      <p className="changes">{changes} changes, no jumps</p>
      <div className="buttons">
        <button onClick={() => change(Math.max(0, value - 100))}>−100</button>
        <button onClick={() => change(value + 1)}>+1</button>
        <button onClick={() => change(value + 250)}>+250</button>
        <button onClick={() => change(value * 10)}>×10</button>
        <button onClick={() => change(Math.round(value / 10))}>÷10</button>
        <button className="burst" onClick={() => setBursting(true)} disabled={bursting}>
          Burst ×12
        </button>
      </div>
    </div>
  );
}

styles.css

.counter {
  display: grid;
  justify-items: center;
  gap: 14px;
  padding: 36px 20px 28px;
}

.value {
  font:
    800 clamp(48px, 12vw, 88px)/1.05 system-ui,
    sans-serif;
  font-variant-numeric: tabular-nums;
  letter-spacing: -0.03em;
  color: #0e2e24;
}

.changes {
  margin: 0;
  color: #5b616b;
  font-size: 14px;
}

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

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

.buttons button:hover {
  border-color: #176b52;
}

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

.buttons .burst:disabled {
  opacity: 0.5;
}

依用途分組的 16 個元件

數字與文字、尺寸會變的內容、選擇、清單、手勢、浮層與進度。每個元件都有即時工作台，props 就在旁邊。

所有元件

組合使用

由多個元件組成的完整畫面，每個範例的設定都在範例之外。

所有範例

Web 與 React Native 使用同一個 import

Metro 會選原生實作，Web 打包工具會選 DOM 實作。每個平台都以自己最擅長的方式播放動態。

App.jsx

// Web and React Native: the same import.
import { MotionNumber, MotionList } from '@kkwaenggwari/animated-chorus';

export function Score({ points, players }) {
  return (
    <>
      <MotionNumber value={points} />
      <MotionList items={players} renderItem={(player) => player.name} />
    </>
  );
}

部分	Web	React Native
transform 與 opacity	Web Animations API，彈簧經解析取樣	使用原生驅動的 `Animated`
寬度與高度	Web Animations API	使用 JS 驅動的 `Animated`，因為這屬於版面配置
串流文字	附加字元並淡入；React 每秒只渲染幾次	真正的 `Text`，不淡入直接顯示
底部面板與縮放	頂層的原生 `dialog`	透明的 `Modal`；返回鍵可關閉

兩分鐘上手

安裝、匯入一個元件、傳一個值。

npm install @kkwaenggwari/animated-chorus

難做的互動，已經完成。

本次建置的實測數據

一個標籤加上你的資料

交給瀏覽器播放，React 保持靜止。

隨時中斷，從不跳動。

依用途分組的 16 個元件

數字與文字

內容與尺寸

選擇與翻頁

清單

手勢

浮層

進度

組合使用

Web 與 React Native 使用同一個 import

兩分鐘上手

搜尋