Vue Circular Gauge

A highly customizable circular gauge component for Vue.js applications. Perfect for dashboards, progress indicators, and data visualizations.

Features

• 🎨 Fully customizable colors with threshold support
• 🔄 Optional animations
• 📏 Multiple sizes (xs, sm, md, lg, xl, 2xl)
• 📊 Value display option
• 🔌 Idle mode with customizable icon
• 🚀 Lightweight (~5kb minified)
• 🧩 TypeScript support
• 📦 Vue 3 and Composition API support

Installation

# npm
npm install vue-circular-gauge

# yarn
yarn add vue-circular-gauge

# pnpm
pnpm add vue-circular-gauge

Usage

Global Registration

// main.js or main.ts
import { createApp } from 'vue'
import App from './App.vue'
import VueCircularGauge from 'vue-circular-gauge'

const app = createApp(App)
app.use(VueCircularGauge)
app.mount('#app')

Local Registration

<script setup>
import { Gauge } from 'vue-circular-gauge'
</script>

<template>
  <Gauge :value="75" />
</template>

Examples

Basic Usage

<template>
  <Gauge :value="65" />
</template>

With Custom Colors

<template>
  <Gauge :value="65" primary="#4ade80" secondary="#e2e8f0" />
</template>

With Color Thresholds

<template>
  <Gauge
    :value="currentValue"
    :primary="{
      0: '#ef4444', // red below 30
      30: '#f97316', // orange between 30-60
      60: '#22c55e', // green above 60
    }"
  />
</template>

<script setup>
import { ref } from 'vue'

const currentValue = ref(45)
</script>

With Animation

<template>
  <Gauge :value="75" :showAnimation="true" />
</template>

With Value Display

<template>
  <Gauge :value="75" :showValue="true" />
</template>

With Idle Mode

<template>
  <Gauge :value="75" :idleMode="true" />
</template>

With Custom Idle Icon

<template>
  <Gauge
    :value="75"
    :idleMode="true"
    idleIcon="M10,20 L20,10 L30,20 L40,10 L50,20"
    idleIconColor="#3b82f6"
  />
</template>

Custom Size

<template>
  <!-- Using predefined sizes -->
  <Gauge :value="75" size="xs" />
  <Gauge :value="75" size="sm" />
  <Gauge :value="75" size="md" />
  <Gauge :value="75" size="lg" />
  <Gauge :value="75" size="xl" />
  <Gauge :value="75" size="2xl" />

  <!-- Using custom size (in pixels) -->
  <Gauge :value="75" size="200" />
</template>

Complete Example

<template>
  <Gauge
    :value="value"
    size="lg"
    :gapPercent="8"
    :strokeWidth="12"
    variant="ascending"
    :showValue="true"
    :showAnimation="true"
    :primary="{
      0: '#ef4444',
      30: '#f97316',
      60: '#22c55e',
    }"
    secondary="#e2e8f0"
  />
</template>

<script setup>
import { ref } from 'vue'

const value = ref(75)
</script>

Props

| Prop | Type | Default | Description | | --------------- | ------------------------------------------------------------------- | ---------------- | ------------------------------------------ | | value | number | 0 | Current value of the gauge (0-100) | | size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| number \| string | 'md' | Size of the gauge | | gapPercent | number | 5 | Gap percentage of the gauge | | strokeWidth | number | 10 | Width of the gauge's stroke | | variant | 'ascending' \| 'descending' | 'ascending' | Direction of the gauge progress | | showValue | boolean | false | Whether to show the value inside the gauge | | showAnimation | boolean | false | Whether to animate the gauge on mount | | primary | string \| Record<number, string> | '#10b981' | Primary color or color thresholds | | secondary | string \| Record<number, string> | '#e5e7eb' | Secondary color or color thresholds | | idleMode | boolean | false | Whether to show idle icon instead of value | | idleIconColor | string | 'currentColor' | Color of the idle icon |

License

MIT