spring() — svelte Function Reference

Architecture documentation for the spring() function in spring.js from the svelte codebase.

Function javascript SharedInternal BitFlags calls 5

Entity Profile

SharedInternal→ BitFlags→ spring() — svelte Function Reference

Dependency Diagram

graph TD
  1be4451f_f9ee_5df1_6b9b_d5f88ec472fd["spring()"]
  5230511f_b608_2c86_cb6b_11014fdf94b5["spring.js"]
  1be4451f_f9ee_5df1_6b9b_d5f88ec472fd -->|defined in| 5230511f_b608_2c86_cb6b_11014fdf94b5
  ba16ff3e_8a18_d3c4_15e9_96304b539f51["writable()"]
  1be4451f_f9ee_5df1_6b9b_d5f88ec472fd -->|calls| ba16ff3e_8a18_d3c4_15e9_96304b539f51
  a360a3a5_5250_4fe5_418b_2dcc66c19942["set()"]
  1be4451f_f9ee_5df1_6b9b_d5f88ec472fd -->|calls| a360a3a5_5250_4fe5_418b_2dcc66c19942
  06e615dd_b546_019b_150f_91f3aec71a6b["now()"]
  1be4451f_f9ee_5df1_6b9b_d5f88ec472fd -->|calls| 06e615dd_b546_019b_150f_91f3aec71a6b
  185b398a_1ddd_d231_9999_8110452fa052["loop()"]
  1be4451f_f9ee_5df1_6b9b_d5f88ec472fd -->|calls| 185b398a_1ddd_d231_9999_8110452fa052
  3ad2c03a_74ef_9f21_8ca8_e0d5cefd8eff["tick_spring()"]
  1be4451f_f9ee_5df1_6b9b_d5f88ec472fd -->|calls| 3ad2c03a_74ef_9f21_8ca8_e0d5cefd8eff
  style 1be4451f_f9ee_5df1_6b9b_d5f88ec472fd fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

packages/svelte/src/motion/spring.js lines 68–153

export function spring(value, opts = {}) {
	const store = writable(value);
	const { stiffness = 0.15, damping = 0.8, precision = 0.01 } = opts;
	/** @type {number} */
	let last_time;
	/** @type {Task | null} */
	let task;
	/** @type {object} */
	let current_token;

	let last_value = /** @type {T} */ (value);
	let target_value = /** @type {T | undefined} */ (value);

	let inv_mass = 1;
	let inv_mass_recovery_rate = 0;
	let cancel_task = false;
	/**
	 * @param {T} new_value
	 * @param {SpringUpdateOpts} opts
	 * @returns {Promise<void>}
	 */
	function set(new_value, opts = {}) {
		target_value = new_value;
		const token = (current_token = {});
		if (value == null || opts.hard || (spring.stiffness >= 1 && spring.damping >= 1)) {
			cancel_task = true; // cancel any running animation
			last_time = raf.now();
			last_value = new_value;
			store.set((value = target_value));
			return Promise.resolve();
		} else if (opts.soft) {
			const rate = opts.soft === true ? 0.5 : +opts.soft;
			inv_mass_recovery_rate = 1 / (rate * 60);
			inv_mass = 0; // infinite mass, unaffected by spring forces
		}
		if (!task) {
			last_time = raf.now();
			cancel_task = false;
			task = loop((now) => {
				if (cancel_task) {
					cancel_task = false;
					task = null;
					return false;
				}
				inv_mass = Math.min(inv_mass + inv_mass_recovery_rate, 1);

				// clamp elapsed time to 1/30th of a second, so that longer pauses
				// (blocked thread or inactive tab) don't cause the spring to go haywire
				const elapsed = Math.min(now - last_time, 1000 / 30);

				/** @type {TickContext} */
				const ctx = {
					inv_mass,
					opts: spring,
					settled: true,
					dt: (elapsed * 60) / 1000
				};
				// @ts-ignore
				const next_value = tick_spring(ctx, last_value, value, target_value);
				last_time = now;
				last_value = /** @type {T} */ (value);
				store.set((value = /** @type {T} */ (next_value)));
				if (ctx.settled) {
					task = null;
				}
				return !ctx.settled;
			});
		}
		return new Promise((fulfil) => {
			/** @type {Task} */ (task).promise.then(() => {
				if (token === current_token) fulfil();
			});
		});
	}
	/** @type {SpringStore<T>} */
	// @ts-expect-error - class-only properties are missing
	const spring = {
		set,
		update: (fn, opts) => set(fn(/** @type {T} */ (target_value), /** @type {T} */ (value)), opts),
		subscribe: store.subscribe,
		stiffness,