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