react-springは、バネの物理モデルで値を補間するReact用のアニメーションライブラリです。2026年11月時点の安定版は@react-spring/web 10.1.2(2026年6月24日公開)で、10月1日には次のメジャー版の11.0.0-beta.1が出ました。この記事では、useSpringからuseChainまでの書き方と、v11 betaで入ったusePresenceを、React 19.3.1の上で実際に動かした値つきで整理します。数値はいずれもjsdom上で計測した参考値で、加速中の途中値はフレームの刻み方によって実行環境ごとに変わります。
なお「react spring」で探しているのがJavaのSpring BootとReactをつなぐ方法なら、別の話題です。そちらはSpring BootとReactの連携方法で解説しています。
まとめ:react-springを10.1.2で書くときの要点
- Web向けは
@react-spring/webを入れる。アンブレラのreact-springはv11で配布が終わる。 - React 19ではv10以上が必須。v9.7.5のpeerDependenciesはReact 18まで。
useSpringは設定オブジェクトを渡すとスタイル値だけ、関数を渡すと[スタイル値, API]の配列を返す。- 連結は
useChainとuseSpringRefで組む。refを付けたアニメーションは自動では始まらず、useChainかref.start()で開始する。 useReducedMotionは、OSの視差効果を減らす設定がオンのときreact-springの全アニメーションを補間なしにするスイッチ。ルートで1回だけ呼ぶ。- v11.0.0-beta.1で
usePresence・usePresenceListが入り、useTransitionは非推奨になった。ESM専用化とReact Native対応の削除もv11の破壊的変更。 - レイアウトの入れ替えを自動で補間したいならMotion、物理パラメータで手触りを作り込むならreact-spring。React Nativeはv11以降Reanimatedへ。
インストールとパッケージの選び方
react-springの標準の動き方は、CSSトランジションのような「0.3秒でこの曲線をたどる」という時間指定ではありません。張力(tension)と摩擦(friction)を持つバネの運動をフレームごとに解き、速度を引き継いだまま目標へ寄せます。動作中に目標が変わっても速度が途切れないので、ホバーやドラッグのように入力が続けて変わる操作と相性が良い仕組みです。時間で指定したい箇所だけ、後述のdurationに切り替えられます。
@react-spring/webとアンブレラreact-springの差
npmには@react-spring/webと、全ターゲットをまとめたアンブレラのreact-springがあります。アンブレラの最新10.0.4は、core・konva・native・three・web・zdogの6パッケージに依存しています。ブラウザだけで使うなら、ターゲット別のパッケージを直接入れます。
npm install @react-spring/web
# 本記事の検証版に揃えるなら
npm install @react-spring/[email protected]
公式サイトのトップには、react-springが55.1kb、webが19.2kb、coreが15.2kbという比較が載っています(圧縮方式などの測定条件は書かれていません)。直近1週間(2026年10月26日〜11月1日)のnpmダウンロード数は、@react-spring/webが約698万回、アンブレラが約152万回でした。アンブレラはv11で配布をやめることが決まっているため、新規に選ぶ理由はありません。
React 19ではv10以上が必須
peerDependenciesを版ごとに見ると境目がはっきりします。v9系の最終版9.7.5(2024年10月7日公開)はreact: ^16.8.0 || ^17.0.0 || ^18.0.0で、React 19を含みません。10.0.0(2025年5月15日公開)からReact 19が加わり、10.1.2は^19.0.0まで受け入れます。React 19へ上げたときにpeer依存の警告が出たら、react-springがv9のまま残っていないかを先に確かめてください。
useSpringの使い方|戻り値・config・コールバック
useSpringは1つの要素を動かす基本のフックです。サンプルによって配列で受けたりオブジェクトで受けたりしているのは、呼び方で戻り値が変わる仕様のためです。
オブジェクト渡しと関数渡しで変わる戻り値
型定義には3つのオーバーロードがあります。第1引数が関数のとき、または第2引数に依存配列を渡したときは[SpringValues, SpringRef]の配列を返し、設定オブジェクトだけのときはSpringValuesだけを返します。10.1.2で実行すると、オブジェクト渡しの戻り値は配列ではなく、関数渡しは長さ2の配列で、2番目にstartメソッドを持つAPIが入っていました。
import { useState } from 'react'
import { useSpring, animated } from '@react-spring/web'
// オブジェクト渡し:SpringValues だけが返る
export function FadeIn() {
const styles = useSpring({ from: { opacity: 0 }, to: { opacity: 1 } })
return <animated.div style={styles}>Hello</animated.div>
}
// 関数渡し:[SpringValues, SpringRef] が返る
export function Toggle() {
const [open, setOpen] = useState(false)
const [styles, api] = useSpring(() => ({ opacity: 0 }))
const toggle = () => {
const next = !open
setOpen(next)
api.start({ opacity: next ? 1 : 0 }) // 途中値でなく目標を反転する
}
return (
<>
<animated.div style={styles}>Hello</animated.div>
<button onClick={toggle}>Toggle</button>
</>
)
}
動かす要素はanimated.divのようにanimated経由で描画します。素のdivにSpringValuesを渡した場合、実測ではstyle属性がnullのままでした。関数渡しのapi.startはアニメーションを直接始め、styles.opacity.get()で途中の値を同期的に読めます。上のToggleを実行すると、0だったopacityは0.6秒後に0.997まで進み、停止条件を満たした時点で目標値の1に確定しました。途中値で開閉を判定すると、フェードアウト中のクリックで反転しなくなるため、判定には目標側の状態を使います。開閉状態をpropsやReact Contextで共有しているなら、その状態から目標値を出すオブジェクト渡しのほうが読みやすくなります。
configプリセット6種のtensionとfriction
動きの質感はconfigで決まります。configオブジェクトを読み出すと、プリセットは6種でした。frictionが小さいほど目標を行き過ぎて揺り戻します。
| プリセット | tension | friction | 動き |
|---|---|---|---|
| default | 170 | 26 | 標準 |
| gentle | 120 | 14 | ゆっくり寄る |
| wobbly | 180 | 12 | 大きく揺り戻す |
| stiff | 210 | 20 | 素早く止まる |
| slow | 280 | 60 | 重く止まる |
| molasses | 280 | 120 | 粘って収束 |
ボタンの押下などの操作への反応はstiff、モーダルの出現はgentleから試すと調整が早く済みます。足りなければconfig: { tension: 210, friction: 20 }のように数値で指定します。
durationとeasingによる時間ベースの指定
「400ミリ秒で動かす」と時間で決めたい箇所では、configにdurationを書きます。型定義のコメントどおり、easingはdurationを指定したときだけ効きます。
import { useSpring, easings } from '@react-spring/web'
const styles = useSpring({
from: { x: 0 },
to: { x: 100 },
config: { duration: 400, easing: easings.easeInOutCubic },
})
実行すると500ミリ秒時点でxは100で止まり、バネ特有の行き過ぎは出ませんでした。easingsにはlinearを含む31種の名前付き関数と、階段状に進めるeasings.stepsが入っています。アニメーションを飛ばして値だけ反映するならimmediate: trueで、30ミリ秒時点で目標の100に達していました。
onRestによる完了判定と後処理
閉じるアニメーションが終わってからフォーカスを移す、といった後処理は、setTimeoutで秒数を当てずにonRestで受けます。引数のfinishedで、最後まで動いたか途中で止められたかを判定できます。
const [styles, api] = useSpring(() => ({
opacity: 0,
onRest: result => {
if (result.finished) console.log('完了', result.value.opacity)
},
}))
api.start({ opacity: 1 })の後にapi.stop()を呼ぶと、onRestはfinished: falseと停止時点の値(実測で0.6〜0.7前後)で届きました。走行中に別のstartで目標を上書きしただけなら、ここで宣言したonRestは途中で呼ばれず、最後に1回finished: trueで呼ばれます。ただしapi.start({ x: 1, onRest })のようにstart呼び出しごとに渡したonRestは、10.1.2では上書きされた時点でfinished: falseで発火します。この挙動はv11で変わります(後述)。
複数要素の動かし方|useSprings・useTrail・useTransition
useSpringsとuseTrailはどちらも要素数を第1引数に取りますが、役割が違います。要素ごとに別の値へ動かすならuseSprings、同じ動きを順に後ろへ伝えるならuseTrail、追加と削除そのものを動かすならuseTransitionです。
useSpringsのインデックス別の目標値
useSpringsが返すAPIのstartには関数を渡せて、引数にインデックスが入ります。3要素で偶数番だけopacityを1にすると、0.7秒後の値は1、0、1でした。
import { useSprings, animated } from '@react-spring/web'
export function Highlight({ items }) {
const [springs, api] = useSprings(items.length, () => ({ opacity: 0 }))
const showEven = () => api.start(i => ({ opacity: i % 2 === 0 ? 1 : 0 }))
return (
<>
{springs.map((style, i) => (
<animated.div key={i} style={style}>{items[i]}</animated.div>
))}
<button onClick={showEven}>偶数番を表示</button>
</>
)
}
useTrailによる複数要素の追従アニメーション
useTrailは先頭の値の変化が後ろの要素を順に引っ張るので、要素ごとにdelayを割り振る必要がありません。下のコードを3要素で動かすと、200ミリ秒時点のopacityは先頭から0.75、0.32、0.08でした。
import { useTrail, animated } from '@react-spring/web'
export function TrailList({ items }) {
const trail = useTrail(items.length, {
from: { opacity: 0, x: -20 },
to: { opacity: 1, x: 0 },
})
return trail.map((style, i) => (
<animated.div key={i} style={style}>{items[i]}</animated.div>
))
}
reverse: trueには注意が要ります。伝わる向きが末尾からに変わるだけでなく、fromとtoも入れ替わります。上のコードにreverseを足すと、開始直後のopacityは3要素ともほぼ1で、600ミリ秒後には0.15、0.03、0へ下がりました。「末尾から順に表示」のつもりで足すとフェードアウトになるので、向きだけ変えたいならfromとtoも書き換えます。ドラッグ操作と組み合わせるなら、同じpmndrsの@use-gesture/reactで移動量を受けてapi.startへ渡すか、react-rndでドラッグとリサイズを実装して操作と動きを分けると状態管理が単純になります。
useTransitionによる削除時のアニメーション
Reactでは状態から項目を消すとDOMも即座に消えるため、そのままではフェードアウトさせる対象が残りません。useTransitionは追加・更新・削除に別々のスタイルを割り当て、leaveのアニメーションが終わってからアンマウントします。
import { useTransition, animated } from '@react-spring/web'
export function FadingList({ items }) {
const transitions = useTransition(items, {
keys: item => item.id,
from: { opacity: 0, height: 0 },
enter: { opacity: 1, height: 40 },
leave: { opacity: 0, height: 0 },
})
return transitions((style, item) => (
<animated.div style={style}>{item.label}</animated.div>
))
}
3件から1件を消すと、120ミリ秒後もDOM上の要素は3件のままで、leaveが終わってから2件に減りました。10.1.0ではreverseプロパティが加わり、trailの遅延を後ろの項目から割り当てられるようになっています(こちらは描画順もfromとtoも変えません)。
useChainの連結|SpringRefによる完了待ちと時間差開始
useChainのシグネチャはuseChain(refs, timeSteps?, timeFrame?)で、第2引数の有無で動きが2通りに分かれます。第1引数はuseSpringRef()で作ったrefの配列で、この並びが実行順です。
- timeStepsなし:前のアニメーションが終わるのを待って次を始める。
- timeStepsあり:各アニメーションのdelayに「timeFrame×timeSteps」ミリ秒を足して始める。前の完了は待たない。
10.1.2の実装を読むと、timeStepsありの場合はrefに積まれた各更新のdelayへこの値を加算してからref.start()を呼んでいます。timeFrame(省略時は1000)は開始の遅れを計算する基準の時間で、各アニメーションの長さや終了時刻は縛りません。[0, 0.5]なら「1本目はすぐ、2本目は500ミリ秒後に開始」です。
import { useSpring, useSpringRef, useChain, animated } from '@react-spring/web'
export function ChainedBox() {
const boxRef = useSpringRef()
const textRef = useSpringRef()
const box = useSpring({ ref: boxRef, from: { x: 0 }, to: { x: 100 } })
const text = useSpring({ ref: textRef, from: { y: 0 }, to: { y: 100 } })
useChain([boxRef, textRef], [0, 0.5])
return (
<>
<animated.div style={box}>box</animated.div>
<animated.div style={text}>text</animated.div>
</>
)
}
マウントから150ミリ秒の時点でxは約54まで進み、yは0のままでした。1.55秒後には両方が100に届いています。refを付けたアニメーションは自動では始まりません。refを付けてuseChainもref.start()も呼ばずにいると、0.8秒経ってもxは0のままでした。「refを付けたら動かなくなった」ときは、useChainかref.start()のどちらかで開始しているかを確かめてください。
スクロール連動と可視判定|useInView・useScroll
@react-spring/webには、useInView・useScroll・useResize・useSpringValueも入っています。IntersectionObserverやscrollイベントを自分で書かずに、可視状態やスクロール量をバネの値として受け取れます。
useInViewは引数なしで呼ぶと[ref, boolean]を返し、第1引数にスプリングを返す関数を渡すと[ref, SpringValues]を返します。「画面に入ったらフェードイン」なら後者が短く書けます。
'use client'
import { useInView, animated } from '@react-spring/web'
export function FadeInOnScroll() {
const [ref, styles] = useInView(
() => ({ from: { opacity: 0 }, to: { opacity: 1 } }),
{ once: true }
)
return <animated.div ref={ref} style={styles}>見えたら表示</animated.div>
}
once: trueを付けると一度可視になった時点で監視をやめ、往復スクロールしても再生は1回です。これらのフックはブラウザAPIを読むため、Next.jsのApp Routerでは呼び出すファイルの先頭に'use client'が要ります。
useReducedMotionの副作用|アプリ全体を止めるスイッチ
useReducedMotionは真偽値を返すだけのフックに見えますが、10.1.2の実装はprefers-reduced-motionの変化のたびにGlobals.assign({ skipAnimation: e.matches })を呼びます。Globalsはライブラリ全体の共有設定なので、OSの視差効果を減らす設定がオンの利用者では、1つのコンポーネントで呼んだだけでアプリ内のreact-springの全アニメーションが補間を省き、目標値へ即座に移ります。CSSや他のライブラリのアニメーションは対象外です。v11.0.0-beta.1でも実装は同じでした。
癖が2つあります。後片付けはmatchMediaのリスナーを外すだけでskipAnimationを戻さないため、呼んだコンポーネントがアンマウントされても停止は残ります。また初回レンダーの戻り値はuseState(null)のnullで、if (!reducedMotion)と書くと初回だけ「設定オフ」の分岐に入ります。サーバーで描画するHTMLもこの分岐で書き出されるので、CSSクラスの切り替えなどに使うならreducedMotion === trueと明示的に比べてください。
結論として、useReducedMotionはアプリのルートで1回だけ呼びます。一部のコンポーネントだけ動きを止めたいなら、このフックは使わずに自分でmatchMediaを読み、useSpringのimmediateへ渡すほうが影響範囲を閉じられます。
v11 betaで変わること|usePresenceとonRestの挙動
v11はまだbetaで、npmのlatestは10.1.2のままです。ただし既存コードに影響する変更が11.0.0-beta.0(npmへの公開は日本時間2026年6月22日)と11.0.0-beta.1に入っているので、今のうちに書き方を寄せておくと移行が軽くなります。同じコードを10.1.2と11.0.0-beta.1で動かした結果は次のとおりです。
| 項目 | 10.1.2 | 11.0.0-beta.1 |
|---|---|---|
| 上書き時のstart個別onRest | finished: falseで発火 | 発火しない |
| 配列toとimmediate | 0→1.1→4.0と動く | 0→50→100と飛ぶ |
| usePresence | なし | あり |
| useTransition | 通常 | 非推奨(動作する) |
| CommonJSビルド | 同梱 | なし(ESMのみ) |
usePresence・usePresenceListとuseTransitionの非推奨化
ここからのコードは10.1.2には無いAPIを使うため、試すときはnpm install @react-spring/web@beta(2026年11月時点で11.0.0-beta.1)を入れます。beta.1のPR #2590で、出し入れのアニメーション用に2つのフックが加わりました。useTransitionは描画関数を返す形で、itemがどこから来るか分かりにくいことが理由に挙げられています。useTransitionと<Transition>は削除ではなく非推奨で、既存コードはそのまま動きます。
import { usePresence, usePresenceList, animated } from '@react-spring/web'
// 1要素の出し入れ:leave が終わると null を返す
export function Modal({ open }) {
const presence = usePresence(open, {
from: { opacity: 0 },
enter: { opacity: 1 },
leave: { opacity: 0 },
})
return presence && <animated.div style={presence.springs}>モーダル</animated.div>
}
// リスト:普通の配列として map できる
export function List({ items }) {
const entries = usePresenceList(items, {
keys: item => item.id,
from: { opacity: 0 },
enter: { opacity: 1 },
leave: { opacity: 0 },
})
return entries.map(({ key, item, springs }) => (
<animated.li key={key} style={springs}>{item.label}</animated.li>
))
}
openをfalseにして120ミリ秒後は、presence.phaseが'leave'で要素はまだDOMにあり、1.3秒後には戻り値がnullになって要素が消えました。usePresenceListも、3件から1件を消した120ミリ秒後は3件のままで、各entryのphaseがenter, leave, enterと出ていました。phaseを読めるので、退出中だけクリックを無効にする、といった分岐が描画関数を経由せずに書けます。
onRest・immediate・ref.startの破壊的変更
PR #2467により、走行中に新しい目標を与えたとき、前のアニメーションのonRestは呼ばれなくなりました。上の表のとおり、10.1.2でstartごとに渡したonRestに後処理を書いていると、v11では呼ばれる回数が減ります。目標が上書きされたことを知りたい場合は、start()の戻り値のfinished: falseで判定するようにPRで案内されています。useSpringValueのstart()はPromiseを1つ返しますが、useSpringのapi.start()はPromiseの配列を返すので、Promise.allで待ってから各結果のfinishedを見ます。
toを配列やasync関数で書いた連続アニメーションでは、v10まで全体に付けたimmediateが各ステップに届いていませんでした。PR #2580で各ステップが継承するようになり、実測でも値は0、50、100と途中を補間せずに最終値へ飛びました。v10でdefault: { immediate: true }と書いて回避していたコードは、v11では不要になります。さらにPR #2582で、ref付きのuseSpringに宣言したconfigとイベントがref.start(props)にも効くようになりました。
ESM専用化とReact Native対応の削除
beta.0のPR #2544でビルドはESMのみになりました。Vite・webpack 5・Next.jsなどESMで解決する構成は影響を受けません。CommonJSのまま使うには、ESMをrequire()で読める版のNode(20.19.0以降、または22.12.0以降)が必要で、Webpack 4はサポート外です。JestがCommonJSへ変換して読み込む構成も確認が要ります。
PR #2526では、アンブレラのreact-springと、native・konva・zdogの各ターゲットが配布終了になりました。残るのはwebとthreeです。PRには、react-springはバネの計算をJSスレッドで行いReact Nativeのネイティブドライバーを使わないため、React NativeにはUIスレッドで動くReanimatedが適している、と書かれています。
Reactのアニメーションライブラリの選び分け
react-springが合うのは、ドラッグの慣性やホバーの追従のように、動きの手触りをtensionとfrictionで作り込みたい場面です。逆に、次の条件に当てはまるなら別の手段を選びます。
| やりたいこと | 向く手段 | 週間DL数 |
|---|---|---|
| 物理パラメータで手触りを作る | react-spring | 約698万(web) |
| レイアウト変化の自動補間 | Motion | 約6,598万(framer-motion) |
| タイムラインで長い演出 | GSAP | 約859万 |
| ページや画面の切り替え | View Transitions | ブラウザ標準 |
| React Nativeのアプリ | Reanimated | – |
週間DL数は2026年10月26日〜11月1日のnpm集計です。framer-motionの数には、motionパッケージ経由で入る分も含まれます。
レイアウト変化ならMotion、長い演出ならGSAP
要素の並べ替えや開閉で位置とサイズが変わるのを自動で補間したいなら、layoutプロパティを持つMotionのほうが短く書けます。MotionにもuseSpringという同名のフックがありますが、MotionValueか数値・文字列を第1引数に取る別物で、react-springのuseSpring({ from, to })とは引数も戻り値も違います。書き方はFramer Motion(現Motion)の使い方とspringの既定値にまとめています。スクロールに合わせて何十もの要素を順番に動かす演出は、タイムラインで並べられるGSAPが向きます。GSAPとAnime.jsの違いはAnime.js v4の使い方とGSAPとの違いを参照してください。画面全体の切り替えなら、ライブラリを足さずにReact 19.3のViewTransitionで済む場合もあります。
動きの方針をデザインの段階から詰めたい場合は、一創のUI/UXデザイン支援でも、画面設計と合わせてマイクロインタラクションの仕様化から相談を受けています。
react-motionからの移行
名前の似たreact-motionは、npmの最新版が0.5.2(2017年10月3日公開)で、以後9年以上リリースがありません。新規に選ぶ理由はなく、Reactのメジャー版を上げるタイミングでreact-springへ移すのが現実的です。<Motion>の子に関数を渡して補間済みスタイルを受け取っていた部分をuseSpringに置き換え、描画をanimated.divに変えます。spring(value, { stiffness, damping })はconfig: { tension, friction }に対応し、react-motion 0.5.2のプリセットnoWobble(170・26)、gentle(120・14)、wobbly(180・12)、stiff(210・20)は、react-springのdefault・gentle・wobbly・stiffと数値がすべて一致します。
よくある質問
react-springと@react-spring/webのどちらをインストールすべきですか?
ブラウザ向けなら@react-spring/webです。アンブレラのreact-springは6パッケージに依存するうえ、v11では配布が終わります。
useSpringの戻り値が配列のときとオブジェクトのときがあるのはなぜですか?
オーバーロードの仕様です。第1引数が関数、または第2引数に依存配列を渡すと[SpringValues, SpringRef]の配列が返り、設定オブジェクトだけならSpringValuesが返ります。styles.opacityがundefinedになるときは、受け方が逆になっていないかを確認してください。
React 19でreact-springは動きますか?
v10以上なら動きます。React 19への対応は10.0.0(2025年5月15日公開)で入り、v9系最終の9.7.5はReact 18までです。
useTransitionはもう使わないほうがよいですか?
10.1.2では通常どおり使えます。11.0.0-beta.1で非推奨になりましたが削除はされておらず、既存コードは動きます。v11へ上げる予定があるなら、1要素はusePresence、リストはusePresenceListで書き始めると移行の手間が減ります。
react-springはReact Nativeで使えますか?
10.1.2までは@react-spring/nativeがありますが、v11で配布終了になります。これからReact Nativeで書くならReanimatedを選んでください。