# useTime > A motion value that ticks once per animation frame with elapsed milliseconds. **Source:** [https://motion.svelte.page/docs/use-time](https://motion.svelte.page/docs/use-time) --- `useTime` returns a motion-dom `MotionValue` that updates once per animation frame with elapsed milliseconds since the value was created. It's a real motion value augmented with a `$state`-backed `.current` getter and a Svelte readable `.subscribe` shim — so it composes with `useTransform`, `useSpring`, and the rest of the Tier 2 surface. ```svelte
Rotating content
``` ## Usage The store value represents elapsed milliseconds, making it perfect for time-based animations that need to stay in sync with Svelte's reactivity system. ```svelte
Animated content
``` > Live example: [/examples/use-time](https://motion.svelte.page/examples/use-time) ## Shared timelines Pass an `id` string to share the same RAF loop **across multiple components**. Each call returns its **own** motion value — destroying one consumer's value doesn't ripple to others — but they all observe the same underlying timeline, so the values stay perfectly in lockstep. The shared loop runs while at least one consumer is alive and stops the moment the last one unmounts; the next `useTime(id)` call restarts it. > **Note**: Within a single component, you can simply reuse the same motion-value reference. The `id` parameter is specifically useful for synchronizing animations across different components that don't share scope. ```svelte
Synced animation
``` ### Multiple components synchronized ```svelte
Time: {$time}ms
Same time: {$time}ms
``` Even though these are **separate components**, they both receive updates from the same timeline by using the same `id`, ensuring perfect synchronization. ### Synced timeline example Here's a complete example demonstrating the power of shared timelines. Notice how two **separate** `useTime()` calls with the same `id` return independent-but-synchronized motion values — different references, identical values every frame: ```svelte
A
B
time: {$time}ms = time2: {$time2}ms
``` > Live example: [/examples/use-time-synced](https://motion.svelte.page/examples/use-time-synced) Both elements animate in perfect synchronization even though they use **different motion-value references** (`time` and `time2`). The magic happens because both `useTime('synced-timeline')` calls observe the same underlying timeline — independent values, shared frame loop. Watch the values display - they're always identical! This is especially powerful when these elements live in **separate components** - the `id` parameter ensures they all stay in sync without prop drilling or context. ## How it works `useTime` wraps motion-dom's `MotionValue` with a per-frame RAF loop: 1. Creates a `MotionValue` that writes elapsed milliseconds on every `requestAnimationFrame` 2. With an `id`, multiple consumers observe the **same** RAF loop — each call still returns an independent motion value (so destroying one doesn't affect others) but they stay in lockstep 3. The RAF loop attaches at component mount via `$effect` and detaches at unmount — when the last consumer of a shared `id` unmounts, the loop stops; the next `useTime(id)` call restarts it ### Read patterns ```svelte ``` The RAF loop starts at component mount and stops at unmount — no subscriber tracking required. ## Performance `useTime` is optimized for smooth animations: - **Frame-perfect**: Updates at display refresh rate (typically 60 FPS) - **Efficient**: Single `requestAnimationFrame` loop per unique timeline - **Shared resources**: Multiple consumers of the same `id` share one loop - **Auto-cleanup**: Cancels the frame loop on component unmount ## Common patterns ### Smooth rotation ```svelte
↻
``` ### Oscillating scale ```svelte
Pulsing
``` ### Color cycling ```svelte
Rainbow
``` ### Multiple synchronized animations ```svelte
Complex animation
``` ## API Reference ### Parameters - **id** `string` (optional) - Timeline identifier for sharing across components ### Returns An `AugmentedMotionValue` — a real motion-dom `MotionValue` containing elapsed milliseconds since creation, plus: - `.current` — Svelte 5 reactive getter (templates, `$derived`, `$effect`). - `.subscribe(run)` — Svelte readable store contract (powers `$time` template syntax and `derived(time, …)`). - `.get()` / `.on('change', cb)` / all other motion-value methods from motion-dom. The motion value's lifecycle is bound to the surrounding `$effect`: the RAF loop starts at mount and stops at unmount. For shared `id` timelines the loop stops only when the last consumer unmounts. ## When to use Use `useTime` when you need: - **Reactive time values** - Integrate time into Svelte's reactive system - **Store-based animations** - Derive multiple animated values from one timeline - **Cross-component synchronization** - Keep separate components in sync with shared timeline `id` - **Declarative time** - Use `$time` syntax for clean, reactive code For direct DOM manipulation or frame-by-frame control, consider [useAnimationFrame](/docs/use-animation-frame) instead. ## Comparison with useAnimationFrame | Feature | useTime | useAnimationFrame | |---------|---------|-------------------| | Returns | Reactive store | Cleanup function | | Usage | Declarative with `$` | Imperative callback | | Integration | Svelte stores | Direct DOM | | Derived values | Easy with `derived()` | Manual calculation | | Synchronization | Built-in with `id` | Manual coordination | ## See also - [useAnimationFrame](/docs/use-animation-frame) - For direct frame control - [useTransform](/docs/use-transform) - For mapping and transforming values - [styleString](/docs/style-string) - For building CSS style strings with automatic unit handling - [Examples](/examples) - See useTime in action --- Based on [Motion's useTime](https://motion.dev/docs/react-use-time) API.