Vue CountUp v3

Common errors

• Module 'vue-countup-v3' could not be resolved in Nuxt 3 build or similar build-time errors.

  cause Nuxt 3's build process isn't automatically transpiling the 'vue-countup-v3' package.
  fix Add 'vue-countup-v3' to the `transpile` array in your `nuxt.config.ts`: `export default defineNuxtConfig({ build: { transpile: ['vue-countup-v3'] } });`

• Hydration mismatch error or component not rendering on the client-side in Astro.

  cause Astro requires explicit client-side rendering directives for interactive UI frameworks.
  fix Add `client:load client:only` directives to your `CountUp` component within Astro: `<CountUp client:load client:only :end-val="2000" />`

• TS2724: 'ICountUp' is not a runtime value and cannot be used in 'import' type checking. (or similar for 'CountUpOptions')

  cause Attempting to import TypeScript types using a standard runtime 'import' statement, which leads to compilation errors or unexpected bundling behavior.
  fix Change your type imports from `import { ICountUp, CountUpOptions } from 'vue-countup-v3'` to `import type { ICountUp, CountUpOptions } from 'vue-countup-v3'`.

Warnings

• gotcha When integrating `vue-countup-v3` into a Nuxt 3 project, you must explicitly configure Nuxt to transpile the package. Without this, you might encounter build errors or issues with client-side hydration.
  Fix: Add 'vue-countup-v3' to the `build.transpile` array in your `nuxt.config.ts` file: `build: { transpile: ['vue-countup-v3'] }`.
• gotcha In Astro projects, `vue-countup-v3` is a client-side component and requires explicit client-side rendering directives to function correctly. Without these, the component will not render or hydrate properly.
  Fix: Apply client-side directives such as `client:load` and `client:only` to the component in your Astro templates (e.g., `<CountUp client:load client:only end-val={2000} />`).
• gotcha The component wraps `countUp.js`, and most direct `countUp.js` configuration options should be passed via the `:options` prop as an object. Avoid trying to pass these directly as root component props unless they are explicitly documented as such by `vue-countup-v3`.
  Fix: Refer to the `countUp.js` documentation for available options and provide them as a JavaScript object to the `:options` prop of the `CountUp` component.
• gotcha The `delay` prop specifically controls the interval *between loops* when the `loop` prop is enabled. It does not introduce an initial delay before the very first animation begins.
  Fix: If an initial delay before the first animation is required, implement it externally using Vue's reactivity system (e.g., `setTimeout`) to conditionally render the component or update its `end-val` after the desired delay.

Install

• npm install vue-countup-v3 npm
• yarn add vue-countup-v3 yarn
• pnpm add vue-countup-v3 pnpm

Imports

• CountUp
  wrong:

  const CountUp = require('vue-countup-v3')

  correct:

  import CountUp from 'vue-countup-v3'

  This is the default export for the Vue 3 component. The CommonJS 'require' style is incorrect for modern Vue/ESM setups.
• ICountUp
  wrong:

  import { ICountUp } from 'vue-countup-v3'

  correct:

  import type { ICountUp } from 'vue-countup-v3'

  For TypeScript, use 'import type' for type-only imports to prevent them from being bundled as runtime code, which can cause issues.
• CountUpOptions
  wrong:

  import { CountUpOptions } from 'vue-countup-v3'

  correct:

  import type { CountUpOptions } from 'vue-countup-v3'

  As with ICountUp, use 'import type' for type-only imports in TypeScript to ensure they are removed during compilation.

Quickstart

Demonstrates a comprehensive usage of the CountUp component including reactive end values, custom options, loop/delay props, and event handling for initialization and completion.

<script setup lang="ts">
  import { ref } from 'vue'
  import CountUp from 'vue-countup-v3'
  import type { ICountUp, CountUpOptions } from 'vue-countup-v3'
  
  const endValueRef = ref(2022.22)
  // coutup.js options
  const options: CountUpOptions = {
    separator: '❤️'
    // ... other countUp.js options
  }
  let countUp: ICountUp | undefined
  const onInit = (ctx: ICountUp) => {
    console.log('init', ctx)
    countUp = ctx
  }
  const onFinished = () => {
    console.log('finished')
  }
</script>

<template>
  <count-up 
    :end-val="endValueRef"
    :duration="2.5"
    :decimal-places="2"
    :options="options"
    :loop="2"
    :delay="2"
    @init="onInit"
    @finished="onFinished"></count-up>
</template>