This project is made only for personal use, as a small and lightweight build of tm-odometer, which is itself a fork of HubSpot’s odometer.
⚠️ Do not use this, use @mtmarco87’s package instead.
Huge props to him for this TypeScript refactor !

No theme is shipped here, no docs either.

What’s changed ?

For a quick overview in a real-world usage, see https://github.com/EDM115/website/blob/master/app/components/ui/Odometer.vue

Breaking changes

• Renamed from TmOdometer to LightOdometer
• Removal of all built artifacts, themes, demo, screenshots and CoffeeScript code
• Switch from Rollup to tsdown (Rolldown)
• Remove compatibility layers (Internet Explorer, jQuery)
• Keep only the ESM build and switch to a default export

New features

• SSR friendly (you can import it top-level without blowing up) and use safe fallbacks for browser-land functions
• Each instance can now have an id
• Ability to customize the framerate
  ts Copy

  const odo = new LightOdometer({ ..., framerate: 20 })
  // default is 30, going above isn't recommended
  // use countFramerate if you use the `count` mode instead of `slide`
  

• Ability to render once and destroy the instance
  ts Copy

  const odo = new LightOdometer({ ..., value: 0 })
  odo.animateOnceAndDisconnect(12345)
  

• Expose duration as a CSS property to sync up JS and CSS animations
  ts Copy

  const odo = new LightOdometer({ ..., duration: 5000 })
  console.log(getComputedStyle(odo.el).getPropertyValue("--odometer-duration")) // "5000ms"
  

• Get and mutate instance and global options
  ts Copy

  const odo = new LightOdometer({ ... })
  console.log(odo.getOptions().duration)
  odo.setOptions({ duration: 2000 })
  
  console.log(LightOdometer.getGlobalOptions.selector)
  LightOdometer.setGlobalOptions({ selector: ".my-odometer" })
  

• Add per-instance subscriptable animation start/end events, they give back the instance id, el, instance, value, oldValue, options
  ts Copy

  const odo = new LightOdometer({ ... })
  console.log(odo.isAnimating)
  
  function onStart(e: Event) {
    const { detail } = e as CustomEvent<LightOdometerEventDetail>
    // detail.id, detail.value, detail.instance.isAnimating, ...
    console.log(`started animating to ${detail.value}`)
  }
  
  function onDone(e: Event) {
    const { detail } = e as CustomEvent<LightOdometerEventDetail>
    console.log(`finished animating to ${detail.value}`)
  }
  
  odo.on("odometerstart", onStart)
  odo.on("odometerdone", onDone)
  
  // later
  odo.off("odometerstart", onStart)
  odo.off("odometerdone", onDone)
  

• Print the instance as a JSON-friendly string
  ts Copy

  const odo = new LightOdometer({ ... })
  console.log(odo.toString())
  

  json Copy

  {
    "id": 2,
    "value": 157,
    "options": {
      "id": 2,
      "value": 0,
      "animation": "slide",
      "duration": 8000,
      "format": "( ddd)",
      "framerate": 20
    },
    "globalOptions": {},
    "watchMutations": false,
    "transitionEndBound": true,
    "destroyed": false,
    "format": {
      "repeating": " ",
      "precision": 0
    },
    "isAnimating": false
  }
  

Animation controls

maxValues caps each slide ribbon at 32 value elements by default (configurable from 2 to 256). framerate can lower the sampling density further, it does not throttle CSS animation frames. Digit containers are reused between renders.
Timing changes made with setOptions() apply to the next animation. Format changes apply immediately, including when the numeric value stays the same. A new update() supersedes the previous animation, only the current animation emits odometerdone.
respectReducedMotion defaults to true. Reduced motion and a zero duration render the target immediately while preserving the start/done event order. disconnect() cancels work, restores wrapped element properties, removes subscriptions registered with on() and leaves a static target. Disconnected instances are terminal, create a new instance to reuse the element.
Use onRender to decorate the complete digit structure synchronously without a mutation observer. The callback runs on the initial render as well as later renders, keep it limited to decorating the DOM.

const odo = new LightOdometer({
  el,
  value: 0,
  maxValues: 32,
  respectReducedMotion: true,
  onRender(instance) {
    // instance.inside contains the complete structure
    // instance.digits is ordered from the least significant digit
  },
})

spin(digitCount) rolls 1–32 digits continuously using 11 value elements per digit. duration controls a full revolution with a small speed difference between columns. It keeps the last numeric value unchanged and emits a start event, it has no done event until a later numeric update completes. isSpinning distinguishes this mode from a finite animation. Under reduced motion or zero duration, the requested digits remain stationary. A change in the motion preference updates a running spinner automatically.

odo.spin(6)
odo.update(123456) // Stops spinning and settles on this value
odo.disconnect() // Also stops an active spinner

Numeric inputs must be finite and safely representable after scaling to the format precision, formats support up to 15 decimal places. Invalid values, negative durations, and nonpositive framerates throw RangeError. Use spin() for indefinite motion instead of passing numeric Infinity.
For an accessible integration, expose a separate formatted text value and mark the decorative wheel aria-hidden="true".

Improvements

• value is now stripped from spaces
• Multiple performance improvements
• Use overall more optimized methods
• Stabilize and simplify the interfaces

Other changes

• No more const functions
• Better TS config and stricter types (no more any nor as)
• Use classes private elements
• Added linting and formatting (OxLint + ESLint Stylistic)
• Target ES2023 instead of ES2015