Sparkline Vue

A Vue.js component library for creating sparkline charts, rewritten from the popular jQuery Sparkline library v2.1.2. This library provides lightweight, inline charts perfect for dashboards and data visualization.

Interactive Demos

https://iclaxton.github.io/sparkline-vue/

Features

🎯 7 Chart Types: Line, Bar, Tristate, Discrete, Bullet, Pie, and Box plots
⚡ High Performance: Canvas-based rendering for smooth performance
🎨 Highly Customizable: Extensive configuration options
📱 Responsive: Automatic sizing and responsive design
🚀 Vue 3 Compatible: Built for Vue 3 Composition API
📦 Zero Dependencies: No jQuery required
🎭 TypeScript Ready: Full TypeScript support with declaration files

Installation

npm install sparkline-vue
# or
yarn add sparkline-vue
# or
pnpm add sparkline-vue

Basic Usage

<template>
  <div>
    <!-- Line chart -->
    <Sparkline 
      :data="[1, 4, 6, 6, 8, 5, 3, 5]" 
      type="line" 
      :width="100" 
      :height="30" 
    />
    
    <!-- Bar chart -->
    <Sparkline 
      :data="[1, 4, 6, 6, 8, 5, 3, 5]" 
      type="bar" 
      :width="100" 
      :height="30"
      :options="{ barColor: '#3366cc' }"
    />
  </div>
</template>

<script>
import Sparkline from 'sparkline-vue';

export default {
  components: {
    Sparkline
  }
}
</script>

Component Usage Notes

The component is registered as Sparkline (PascalCase). In Vue templates, you can use either:

<Sparkline> (PascalCase - recommended for SFC templates)
<sparkline> (kebab-case - required for in-DOM templates)

Both are equivalent, but PascalCase is recommended when using Single File Components (.vue files).

Chart Types

Line Chart

Perfect for showing trends over time.

<Sparkline 
  :data="[1, 4, 6, 6, 8, 5, 3, 5]" 
  type="line"
  :options="{
    lineColor: '#00f',
    fillColor: '#cdf',
    spotColor: '#f80',
    spotRadius: 2
  }"
/>

Multi-Series Line Charts

Compare multiple data series on the same chart.

<Sparkline 
  :data="[
    [10, 15, 20, 18, 25, 30, 28],  // Series 1
    [15, 18, 22, 20, 26, 28, 30],  // Series 2
    [12, 17, 21, 19, 24, 29, 27]   // Series 3
  ]"
  type="line"
  :width="300"
  :height="100"
  :options="{
    seriesNames: ['Sales', 'Target', 'Forecast'],
    lineColor: ['#0066cc', '#ff6600', '#00cc66'],
    fillColor: ['rgba(0,102,204,0.15)', 'rgba(255,102,0,0.15)', 'rgba(0,204,102,0.15)'],
    lineWidth: [2, 2, 2],
    spotRadius: 0  // Hide spots for cleaner multi-series view
  }"
/>

Features:

Automatic high-contrast color palette when colors not specified
Tooltips show all series values at cursor position
Supports per-series customization (colors, widths, spot radii)
Series names displayed in tooltips
Maintains full interactivity (hover, click events)

Bar Chart

Great for comparing discrete values.

<Sparkline 
  :data="[1, 4, 6, -2, 8, 5, -3, 5]" 
  type="bar"
  :options="{
    barColor: '#3366cc',
    negBarColor: '#f44',
    barWidth: 4,
    barSpacing: 1
  }"
/>

Tristate Chart

Shows win/lose/draw states.

<Sparkline 
  :data="[1, -1, 0, 1, 1, 0, -1]" 
  type="tristate"
  :options="{
    posBarColor: '#6f6',
    negBarColor: '#f44',
    zeroBarColor: '#999',
    stateLabels: { positive: 'Win', zero: 'Draw', negative: 'Loss' }
  }"
/>

Custom State Labels Example:

<!-- Use custom labels for different contexts -->
<Sparkline 
  :data="[1, -1, 0, 1, 1]" 
  type="tristate"
  :options="{
    stateLabels: { positive: 'Up', zero: 'Flat', negative: 'Down' }
  }"
/>

Discrete Chart

Vertical lines at different heights.

<Sparkline 
  :data="[1, 3, 4, 5, 5, 3, 4, 5]" 
  type="discrete"
  :options="{
    lineColor: '#00f',
    thresholdColor: '#f00',
    thresholdValue: 3
  }"
/>

Bullet Chart

Performance vs target visualization.

<Sparkline 
  :data="[10, 12, 12, 9, 7]" 
  type="bullet"
  :options="{
    targetColor: '#f33',
    performanceColor: '#33f',
    rangeColors: ['#d3dafe', '#a8b6ff', '#7f94ff']
  }"
/>

Pie Chart

Simple proportional visualization.

<Sparkline 
  :data="[1, 1, 2]" 
  type="pie"
  :options="{
    sliceColors: ['#3366cc', '#dc3912', '#ff9900'],
    borderWidth: 1
  }"
/>

Box Plot

Statistical data distribution.

<Sparkline 
  :data="[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]" 
  type="box"
  :options="{
    boxLineColor: '#000',
    boxFillColor: '#cdf',
    whiskerColor: '#000'
  }"
/>

Configuration Options

Common Options

All chart types support these options:

Option	Type	Default	Description
`width`	Number	100	Chart width in pixels
`height`	Number	30	Chart height in pixels
`lineColor`	String	'#00f'	Primary line/border color
`fillColor`	String	'#cdf'	Fill color
`disableTooltips`	Boolean	false	Disable all tooltips
`showTooltipTitle`	Boolean	true	Show title in multi-value tooltips
`tooltipPrefix`	String	''	Text to prepend to tooltip values
`tooltipSuffix`	String	''	Text to append to tooltip values

Line Chart Options

Option	Type	Default	Description
`spotColor`	String	'#f80'	Color of end spots
`spotRadius`	Number	1.5	Radius of spots
`lineWidth`	Number	1	Width of the line
`minSpotColor`	String	'#f80'	Color of minimum value spot
`maxSpotColor`	String	'#f80'	Color of maximum value spot
`normalRangeMin`	Number	undefined	Lower bound of normal range
`normalRangeMax`	Number	undefined	Upper bound of normal range
`normalRangeColor`	String	'#ccc'	Color of normal range
`dataLabels`	Array	undefined	Labels for each data point (e.g., ['Jan', 'Feb', 'Mar'])
`getPointDataLabel`	Function	undefined	Callback function to generate labels: `(index) => string`
`seriesNames`	Array	undefined	Names for each series in multi-series charts

Bar Chart Options

Option	Type	Default	Description
`barColor`	String	'#3366cc'	Color for positive bars
`negBarColor`	String	'#f44'	Color for negative bars
`zeroColor`	String	undefined	Color for zero values
`barWidth`	Number	4	Width of each bar
`barSpacing`	Number	1	Space between bars
`zeroAxis`	Boolean	true	Whether to center around zero
`dataLabels`	Array	undefined	Labels for each data point (e.g., ['Q1', 'Q2', 'Q3'])
`getPointDataLabel`	Function	undefined	Callback function to generate labels: `(index) => string`
`seriesNames`	Array	undefined	Names for each segment in stacked bar charts

Tristate Chart Options

Option	Type	Default	Description
`posBarColor`	String	'#6f6'	Color for positive values
`negBarColor`	String	'#f44'	Color for negative values
`zeroBarColor`	String	'#999'	Color for zero values
`stateLabels`	Object	`{ positive: 'Win', zero: 'Draw', negative: 'Loss' }`	Custom labels for the three states
`barWidth`	Number	4	Width of each bar
`barSpacing`	Number	1	Space between bars
`dataLabels`	Array	undefined	Labels for each data point (e.g., ['Game 1', 'Game 2'])
`getPointDataLabel`	Function	undefined	Callback function to generate labels: `(index) => string`

Discrete Chart Options

Option	Type	Default	Description
`lineColor`	String	'#00f'	Default line color
`lineHeight`	Number	'auto'	Height of lines
`thresholdColor`	String	undefined	Color for values above threshold
`thresholdValue`	Number	0	Threshold value
`dataLabels`	Array	undefined	Labels for each data point (e.g., ['Mon', 'Tue', 'Wed'])
`getPointDataLabel`	Function	undefined	Callback function to generate labels: `(index) => string`

Pie Chart Options

Option	Type	Default	Description
`sliceColors`	Array	['#3366cc', '#dc3912', ...]	Colors for pie slices
`borderWidth`	Number	0	Width of slice borders
`borderColor`	String	'#000'	Color of slice borders
`offset`	Number	0	Angle offset in degrees
`dataLabels`	Array	undefined	Labels for each slice (e.g., ['Category A', 'Category B'])
`getPointDataLabel`	Function	undefined	Callback function to generate labels: `(index) => string`
`glowIntensity`	Number	5	Intensity of highlight glow effect (0 to disable)

Bullet Chart Options

Option	Type	Default	Description
`targetColor`	String	'#f33'	Color of target marker
`performanceColor`	String	'#33f'	Color of performance bar
`rangeColors`	Array	['#d3dafe', '#a8b6ff', '#7f94ff']	Colors for range bands
`targetWidth`	Number	3	Width of target line

Box Plot Options

Option	Type	Default	Description
`boxLineColor`	String	'#000'	Color of box outline
`boxFillColor`	String	'#cdf'	Fill color of box
`whiskerColor`	String	'#000'	Color of whiskers
`outlierLineColor`	String	'#333'	Color of outlier markers
`outlierFillColor`	String	'#fff'	Fill color of outlier markers
`medianColor`	String	'#f00'	Color of median line
`showOutliers`	Boolean	true	Whether to show outliers
`target`	Number	undefined	Target value to display
`targetColor`	String	'#4a2'	Color of target marker

Advanced Usage

X-Y Coordinate Data

You can provide coordinate pairs for line charts:

<Sparkline 
  :data="[[1,1], [2.7,4], [3.4,6], [5,6]]" 
  type="line"
/>

Multi-Series Line Charts

Display multiple data series on a single line chart. Perfect for comparing trends, showing actual vs. target, or multi-region analysis.

Basic Multi-Series:

<template>
  <Sparkline 
    :data="multiSeriesData"
    type="line"
    :width="300"
    :height="100"
    :options="multiSeriesOptions"
  />
</template>

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

const multiSeriesData = ref([
  [10, 15, 20, 18, 25, 30, 28],    // Actual sales
  [15, 18, 22, 20, 26, 28, 30]     // Target sales
])

const multiSeriesOptions = {
  seriesNames: ['Actual', 'Target'],
  // Colors auto-assigned if not specified (high-contrast palette)
  lineColor: ['#0066cc', '#ff6600'],
  fillColor: ['rgba(0,102,204,0.15)', 'rgba(255,102,0,0.15)'],
  lineWidth: [2, 2],
  spotRadius: 0  // Optional: hide spots for cleaner look
}
</script>

Auto Colors:

<!-- Uses default high-contrast palette automatically -->
<Sparkline 
  :data="[[1,2,3], [4,5,6], [7,8,9]]"
  type="line"
  :options="{ seriesNames: ['A', 'B', 'C'] }"
/>

Per-Series Customization:

<Sparkline 
  :data="[series1, series2, series3]"
  type="line"
  :options="{
    seriesNames: ['North', 'South', 'West'],
    lineColor: ['#e74c3c', '#3498db', '#2ecc71'],  // Red, Blue, Green
    lineWidth: [3, 2, 1],                           // Emphasize first series
    spotRadius: [2, 0, 0]                           // Spots only on first series
  }"
/>

Features:

Automatic color assignment with 8 high-contrast colors
Tooltips show all series values at hover position
Single vertical line highlights all series simultaneously
Full support for null values and gaps
Maintains chart range across all series
Per-series customization for colors, widths, and spots

Null Values

Null values create gaps in line charts or are omitted in bar charts:

<Sparkline 
  :data="[1, 4, 6, null, null, 5, 3, 5]" 
  type="line"
/>

Dynamic Updates

The component automatically redraws when data changes:

<template>
  <Sparkline :data="dynamicData" type="line" />
</template>

<script>
import { ref, onMounted } from 'vue';

export default {
  setup() {
    const dynamicData = ref([1, 2, 3, 4, 5]);
    
    onMounted(() => {
      setInterval(() => {
        dynamicData.value = Array.from(
          { length: 10 }, 
          () => Math.random() * 100
        );
      }, 1000);
    });
    
    return { dynamicData };
  }
}
</script>

Migration from jQuery Sparkline

If you're migrating from the original jQuery Sparkline library:

Replace $(selector).sparkline(data, options) with <Sparkline :data="data" :options="options" />
Move chart type from options to the type prop
Move width/height from options to props
The rest of the options remain largely the same

jQuery (Old)

$('.sparkline').sparkline([1,4,6,6,8,5,3,5], {
  type: 'line',
  width: 100,
  height: 30,
  lineColor: '#00f',
  fillColor: '#cdf'
});

Vue (New)

<Sparkline 
  :data="[1,4,6,6,8,5,3,5]"
  type="line"
  :width="100"
  :height="30"
  :options="{
    lineColor: '#00f',
    fillColor: '#cdf'
  }"
/>

Advanced Usage

Programmatic Control

Access chart methods for advanced control:

<template>
  <Sparkline 
    ref="chartRef"
    :data="chartData" 
    type="line"
  />
  <button @click="refreshChart">Refresh</button>
</template>

<script setup>
import { ref } from 'vue'
import Sparkline from 'sparkline-vue'

const chartRef = ref(null)
const chartData = ref([1, 2, 3, 4, 5])

const refreshChart = () => {
  chartRef.value?.refresh()
}

// Access chart instance
const getChartDetails = () => {
  const instance = chartRef.value?.getChartInstance()
  console.log('Chart instance:', instance)
}
</script>

Tooltip Customization

Control tooltip appearance and content:

<template>
  <!-- Disable title in tooltips -->
  <Sparkline 
    :data="multiSeriesData"
    type="line"
    :options="{
      showTooltipTitle: false,  // Hide title
      tooltipPrefix: '$',
      tooltipSuffix: ' USD'
    }"
  />
  
  <!-- Custom tooltip formatting -->
  <Sparkline 
    :data="[1, 2, 3, 4, 5]"
    type="bar"
    :options="{
      tooltipPrefix: 'Value: ',
      tooltipSuffix: ' units',
      tooltipFormat: '{{value.2}}'  // 2 decimal places
    }"
  />
</template>

Tooltip Options:

showTooltipTitle: Show/hide title in multi-value tooltips (default: true)
disableTooltips: Completely disable tooltips (default: false)
tooltipPrefix: Text to prepend to values
tooltipSuffix: Text to append to values
tooltipFormat: Template string for formatting (e.g., '{{value.2}}' for 2 decimals)

Event Handling

Listen to chart interactions:

<Sparkline 
  :data="[1,2,3,4,5]"
  type="line"
  @click="handleClick"
  @region-change="handleRegionChange"
/>

<script setup>
const handleClick = (detail) => {
  console.log('Clicked region:', detail.region)
  console.log('Value:', detail.value)
}

const handleRegionChange = (detail) => {
  console.log('Region changed:', detail.region)
  console.log('Previous region:', detail.previousRegion)
}
</script>

Performance Optimization

Use Optimized Mode for Many Charts

When displaying many charts (50+), enable optimized mode:

<Sparkline 
  :data="data"
  :optimized="true"
/>

Benefits:

Object Pooling: Reuses chart instances
Shared Tooltips: One tooltip for all charts
Cached Defaults: Reduces memory allocations
~50% faster rendering with large datasets

Performance Tips

Batch Updates: Update data in batches rather than individual points
Debounce Rapid Changes: Use debounce for frequently updating data
Appropriate Dimensions: Smaller charts render faster
Disable Tooltips: Set disableTooltips: true if not needed
Live Data: Tooltips are automatically preserved during data updates for smooth UX

<script setup>
import { ref } from 'vue'
import { debounce } from 'lodash-es'

const chartData = ref([])

// Debounce rapid updates
const updateData = debounce((newData) => {
  chartData.value = newData
}, 100)
</script>

Accessibility

The component includes built-in accessibility features:

ARIA role: Canvas has role="img"
ARIA label: Descriptive label with chart type and data point count
Keyboard navigation: Accessible through standard tab navigation
Screen reader friendly: Provides context about chart content

Enhancing Accessibility

Provide additional context when needed:

<div role="region" aria-label="Sales performance chart">
  <h3 id="chart-title">Monthly Sales</h3>
  <Sparkline 
    :data="salesData"
    type="line"
    aria-describedby="chart-title"
  />
  <p class="sr-only">
    Sales trend showing {{ salesData.length }} months of data
  </p>
</div>

Common Pitfalls

1. Forgetting Required Props

The component includes helpful validation that will warn you in development mode.

❌ Wrong:

<Sparkline type="line" />
<!-- Console warning: [Sparkline] data prop is required -->

✅ Correct:

<Sparkline :data="[1,2,3,4,5]" type="line" />

2. Passing Non-Numeric Data

❌ Wrong:

<Sparkline :data="['1', '2', '3']" />
<!-- Console warning: [Sparkline] data must be an array -->

✅ Correct:

<Sparkline :data="[1, 2, 3]" />

3. Mutating Props Directly

❌ Wrong:

<script setup>
const data = [1, 2, 3]
data.push(4) // Mutates directly
</script>

✅ Correct:

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

const data = ref([1, 2, 3])
data.value = [...data.value, 4] // Create new array
</script>

4. Not Handling Empty Data

✅ Best Practice:

<template>
  <div v-if="chartData.length > 0">
    <Sparkline :data="chartData" />
  </div>
  <div v-else>
    No data available
  </div>
</template>

5. Incorrect Dimensions

❌ Wrong:

<Sparkline :data="data" width="200px" height="50px" />
<!-- Console warning: [Sparkline] width must be a positive number -->

✅ Correct:

<Sparkline :data="data" :width="200" :height="50" />

Server-Side Rendering (SSR)

The component is SSR-compatible (Nuxt, VitePress, etc.):

<!-- Works in Nuxt without client-only wrapper -->
<Sparkline :data="[1,2,3,4,5]" type="line" />

The component automatically detects server environment and skips canvas operations during SSR.

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import { ref } from 'vue'
import Sparkline, { type SparklineProps } from 'sparkline-vue'

const props: SparklineProps = {
  data: [1, 2, 3, 4, 5],
  type: 'line',
  width: 200,
  height: 50,
  options: {
    lineColor: '#00f',
    fillColor: '#cdf'
  }
}

Testing

The package includes comprehensive tests. To run them:

npm install
npm test

Testing Your Implementation

import { mount } from '@vue/test-utils'
import Sparkline from 'sparkline-vue'

describe('My Sparkline Usage', () => {
  it('renders correctly', () => {
    const wrapper = mount(Sparkline, {
      props: {
        data: [1, 2, 3, 4, 5],
        type: 'line'
      }
    })
    
    expect(wrapper.find('canvas').exists()).toBe(true)
  })
})

Browser Support

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+

Troubleshooting

Charts Not Rendering

Check browser console for error messages
Verify data format is an array of numbers
Ensure dimensions are positive numbers
Check canvas support in your browser

Performance Issues

Enable optimized mode for many charts
Reduce data points if possible
Use appropriate chart dimensions
Disable tooltips if not needed

TypeScript Errors

Update type definitions: npm install sparkline-vue@latest
Check prop types match the interface
Import types: import type { SparklineProps } from 'sparkline-vue'

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

Examples & Development

Quick Start with Examples

Install dependencies:
```
npm install
```
Start the development server:
```
npm run dev
```
Visit: http://localhost:5175/

Available Examples

Check out the /docs directory for comprehensive demos:

🏠 Landing Page - Overview with navigation between all examples
📊 Complete Demo - All 7 chart types with interactive features
🚀 Simple Demo - Basic implementations using Vue 3 from CDN
💬 Tooltip Demo - Advanced tooltip formatting examples
⚡ Vite Demo - Modern Vue SPA with ES modules

Building the Library

npm run build

This creates distributable files in the dist/ directory.

License

This project is licensed under the BSD-3-Clause License - the same license as the original jQuery Sparkline library.

Credits

This library is a Vue.js rewrite of the excellent jQuery Sparkline library v2.1.2 by Gareth Watts (Splunk, Inc.). All chart rendering logic and algorithms are ported from the original implementation.

Name		Name	Last commit message	Last commit date
Latest commit History 76 Commits
.github/workflows		.github/workflows
.help		.help
.tool/create-favicon		.tool/create-favicon
.vscode		.vscode
components		components
docs		docs
renderers		renderers
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
GitVersion.yml		GitVersion.yml
LICENSE		LICENSE
README.md		README.md
index.d.ts		index.d.ts
index.html		index.html
index.js		index.js
jsconfig.json		jsconfig.json
package-lock.json		package-lock.json
package.json		package.json
vite.config.js		vite.config.js
vitest.config.js		vitest.config.js

Folders and files

Latest commit

History

Repository files navigation

Sparkline Vue

Interactive Demos

Features

Installation

Basic Usage

Component Usage Notes

Chart Types

Line Chart

Multi-Series Line Charts

Bar Chart

Tristate Chart

Discrete Chart

Bullet Chart

Pie Chart

Box Plot

Configuration Options

Common Options

Line Chart Options

Bar Chart Options

Tristate Chart Options

Discrete Chart Options

Pie Chart Options

Bullet Chart Options

Box Plot Options

Advanced Usage

X-Y Coordinate Data

Multi-Series Line Charts

Null Values

Dynamic Updates

Migration from jQuery Sparkline

jQuery (Old)

Vue (New)

Advanced Usage

Programmatic Control

Tooltip Customization

Event Handling

Performance Optimization

Use Optimized Mode for Many Charts

Performance Tips

Accessibility

Enhancing Accessibility

Common Pitfalls

1. Forgetting Required Props

2. Passing Non-Numeric Data

3. Mutating Props Directly

4. Not Handling Empty Data

5. Incorrect Dimensions

Server-Side Rendering (SSR)

TypeScript Support

Testing

Testing Your Implementation

Browser Support

Troubleshooting

Charts Not Rendering

Performance Issues

TypeScript Errors

Contributing

Examples & Development

Quick Start with Examples

Available Examples

Building the Library

License

Credits

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 68

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages