Overview
Framework components accept the same chart configuration as Drawing a Chart, through an options prop. Install the @timescope/* package for your framework and follow its guide:
- Vue uses
v-modelto synchronize state. - React pairs props with change callbacks.
- Svelte uses
bind:with Svelte 5 state. - Solid uses signal values and change callbacks.
- Luna uses signal accessors and change callbacks.
Configuration and state
options is a complete chart configuration. Updates replace it, like setOptions(); omitted settings revert to defaults. Keep the same DataSource instances when changing presentation settings to retain loaded data; see source lifetime.
Pass a new complete options object for updates. Vue also observes nested reactive changes.
Navigation state is passed separately from options:
- Omit
timeandzoomto let the chart manage its view. UseinitialFitto fit a range at creation, or setinitialTimeandinitialZoomexplicitly. - Bind
time,zoom, orselectionRangeto synchronize application state with chart interaction. Time changes yieldDecimal | null, zoom changes yieldnumber, and selection changes yield[Decimal, Decimal] | null. - Set
timetonullto follow the clock; this is not the same as omitting the prop.
initialFit applies only when both time and zoom are undefined at creation. Do not combine it with initialTime or initialZoom. These initial props are creation-only; changing them later does not navigate.
initialTime defaults to null and initialZoom to 0; defined time and zoom props take precedence over their initial counterparts. initialFit accepts a range or { range, padding }, with padding in CSS pixels. renderThread and fonts are also creation-only; see component props.
Luna input props accept either a value or an accessor returning that value. Use accessors for reactive inputs, as shown in the Luna guide.
Events and refs
Event handlers and change callbacks receive the changed value directly, except Svelte events, which expose it as event.detail. The changing events preview interaction state, changed events commit it, and animating events report animation progress. animating / onAnimating indicates a time animation; editing / onEditing indicates time editing.
Vue, React, and Svelte refs expose setTime, setZoom, fitTo, prepareView, and nextFrame after mounting, with the same signatures as the core instance. React exports the ref type TimescopeAPI; Vue refs also expose navigation, selection, animation, and editing state. Use a ref's prepared view and nextFrame() when exporting pixels, rather than relying on mount events.
Lifecycle
Components own their mount targets and dispose the Timescope automatically, including listeners registered with its on() method. Manually unsubscribe only if a subscription should end before the instance is disposed. Clean up application-owned timers, data producers, and listeners on external objects yourself on component unmount; see Cleanup.
Set chart dimensions and background with CSS on the host element, using the component's style or class prop. Usually, an explicit height makes the chart easier to read. ready / onReady fires at the first drawable mount and mount / onMount at each drawable mount. These mean the canvas has a non-zero size, not that data loading is complete; use a prepared view and nextFrame() when you need finished pixels.