violin-chartuiViolin chart around Apache ECharts custom series. Gaussian-KDE density halves with quartile box, median dot, and whiskers per group. Theme-aware via registry tokens.
Also available for React ->$pnpm dlx shadcn-vue@latest add https://uipkge.dev/r/vue/violin-chart.json$npx shadcn-vue@latest add https://uipkge.dev/r/vue/violin-chart.json$yarn dlx shadcn-vue@latest add https://uipkge.dev/r/vue/violin-chart.json$bunx shadcn-vue@latest add https://uipkge.dev/r/vue/violin-chart.jsonnpx shadcn-vue@latest add @uipkge/violin-chartInstalls to:app/components/ui/charts/violin-chart/| Name | Type / Values | Default | Required |
|---|---|---|---|
groups | ViolinGroup[] | — | required |
height | number | string | 340 | optional |
option | any | — | optional |
class | string | — | optional |
ariaLabelAccessible name announced for the chart image. Defaults to "Chart". | string | — | optional |
Type aliases from this item's source — use them to shape the data you pass in.
ViolinGroupinterface ViolinGroup {
group: string
values: number[]
}<script setup lang="ts">
import { computed } from 'vue'
import { use } from 'echarts/core'
import { CanvasRenderer } from 'echarts/renderers'
import { CustomChart as EChartsCustomChart } from 'echarts/charts'
import { GridComponent, TooltipComponent, LegendComponent } from 'echarts/components'
import VChart from 'vue-echarts'
import { cn } from '@/lib/utils'
import {
chartColors,
chartTextColor,
chartAxisColor,
chartSplitLineColor,
chartTooltipBg,
chartTooltipBorder,
chartTooltipText,
mergeOptionBlock,
} from '../useChartTheme'
use([CanvasRenderer, EChartsCustomChart, GridComponent, TooltipComponent, LegendComponent])
export interface ViolinGroup {
group: string
values: number[]
}
interface Props {
groups: ViolinGroup[]
height?: number | string
option?: any
class?: string
/** Accessible name announced for the chart image. Defaults to "Chart". */
ariaLabel?: string
}
const props = withDefaults(defineProps<Props>(), {
height: 340,
})
function kde(values: number[], grid: number[]): number[] {
const n = values.length
if (!n) return grid.map(() => 0)
const mean = values.reduce((s, v) => s + v, 0) / n
const sd = Math.sqrt(values.reduce((s, v) => s + (v - mean) ** 2, 0) / n) || 1
const h = 1.06 * sd * Math.pow(n, -0.2) || sd
return grid.map((x) => values.reduce((s, v) => s + Math.exp(-0.5 * ((x - v) / h) ** 2), 0) / (n * h))
}
function quartiles(sorted: number[]) {
const q = (p: number) => sorted[Math.min(sorted.length - 1, Math.floor(p * (sorted.length - 1)))]!
return { q1: q(0.25), med: q(0.5), q3: q(0.75), min: sorted[0]!, max: sorted[sorted.length - 1]! }
}
const GRID_N = 60
const mergedOption = computed(() => {
const all = props.groups.flatMap((g) => g.values)
const lo = Math.min(...all, 0)
const hi = Math.max(...all, 1)
const grid = Array.from({ length: GRID_N }, (_, i) => lo + ((hi - lo) * i) / (GRID_N - 1))
const densities = props.groups.map((g) => kde(g.values, grid))
const maxD = Math.max(...densities.flat(), 1)
const W = 0.42
const series = [
{
type: 'custom',
renderItem: (params: any, api: any) => {
const gi: number = params.dataIndex
const g = props.groups[gi]!
const sorted = [...g.values].sort((a, b) => a - b)
const { q1, med, q3, min, max } = quartiles(sorted)
const dens = densities[gi]!
const cx = api.coord([gi, 0])[0]
const yOf = (v: number) => api.coord([gi, v])[1]
const xOf = (d: number, side: 1 | -1) =>
cx + side * ((d / maxD) * W * Math.abs(api.coord([gi + 1, 0])[0] - cx || 60))
const right = grid.map((v, i) => [xOf(dens[i]!, 1), yOf(v)] as [number, number])
const left = grid.map((v, i) => [xOf(dens[i]!, -1), yOf(v)] as [number, number]).reverse()
const color = chartColors.value[gi % chartColors.value.length]
return {
type: 'group',
children: [
{ type: 'polygon', shape: { points: [...right, ...left] }, style: { fill: color, opacity: 0.45 } },
{
type: 'line',
shape: { x1: cx, y1: yOf(min), x2: cx, y2: yOf(max) },
style: { stroke: chartTextColor.value, lineWidth: 1.5 },
},
{
type: 'line',
shape: { x1: cx, y1: yOf(q1), x2: cx, y2: yOf(q3) },
style: { stroke: color, lineWidth: 7, lineCap: 'round' },
},
{
type: 'circle',
shape: { cx, cy: yOf(med), r: 4.5 },
style: { fill: chartTooltipBg.value, stroke: color, lineWidth: 2 },
},
],
}
},
data: props.groups.map((g) => g.group),
},
]
const userOption: any = props.option ?? {}
const {
series: userSeries,
xAxis: userXAxis,
yAxis: userYAxis,
grid: userGrid,
tooltip: userTooltip,
...userRest
} = userOption
const mergedSeries = Array.isArray(userSeries) ? series.map((s, i) => ({ ...s, ...(userSeries[i] ?? {}) })) : series
return {
color: chartColors.value,
grid: mergeOptionBlock({ left: 16, right: 16, top: 24, bottom: 24, containLabel: true }, userGrid),
tooltip: mergeOptionBlock(
{
trigger: 'item',
backgroundColor: chartTooltipBg.value,
borderColor: chartTooltipBorder.value,
textStyle: { color: chartTooltipText.value, fontSize: 12 },
formatter: (p: any) => {
const g = props.groups[p.dataIndex]
if (!g) return ''
const s = [...g.values].sort((a, b) => a - b)
const { q1, med, q3 } = quartiles(s)
return `${g.group}<br/>n=${g.values.length} median=${med.toFixed(2)}<br/>Q1=${q1.toFixed(2)} Q3=${q3.toFixed(2)}`
},
},
userTooltip,
),
legend: { show: false },
xAxis: mergeOptionBlock(
{
type: 'category',
data: props.groups.map((g) => g.group),
axisLine: { lineStyle: { color: chartAxisColor.value } },
axisLabel: { color: chartTextColor.value, fontSize: 11 },
axisTick: { show: false },
},
userXAxis,
),
yAxis: mergeOptionBlock(
{
type: 'value',
min: lo,
max: hi,
splitLine: { lineStyle: { color: chartSplitLineColor.value } },
axisLabel: { color: chartTextColor.value, fontSize: 11 },
},
userYAxis,
),
series: mergedSeries,
...userRest,
}
})
</script>
<template>
<div
role="img"
tabindex="0"
:aria-label="ariaLabel || 'Violin chart'"
:style="{ height: /^\d+$/.test(String(height)) ? `${height}px` : String(height) }"
:class="cn('focus-visible:ring-ring w-full focus-visible:ring-2 focus-visible:outline-none', props.class)"
>
<VChart :option="mergedOption" :autoresize="true" class="size-full" />
</div>
</template>
export { default as ViolinChart, type ViolinGroup } from './ViolinChart.vue'
import { computed, ref, type ComputedRef } from 'vue'
// Chart palette is driven by Tailwind v4 CSS variables (`--chart-1`..`--chart-5`,
// `--muted-foreground`, `--border`, `--popover`, etc.) so dark/light flips
// happen automatically when the consumer toggles their theme class. The
// values resolve at runtime via `getComputedStyle`, so they pick up whatever
// the consumer set in their own `tailwind.css` -- no fork required.
//
// We bump `themeKey` whenever `<html>` class/style changes (the typical
// shadcn dark-mode pivot) so every consuming `computed` re-resolves and
// downstream ECharts options re-paint.
const themeKey = ref(0)
if (typeof window !== 'undefined') {
// Bump once on the first paint so post-hydration getComputedStyle reads
// the *resolved* CSS values (during SSR-built bundles the very first
// computed pass returns the fallbacks below).
requestAnimationFrame(() => themeKey.value++)
new MutationObserver(() => themeKey.value++).observe(document.documentElement, {
attributes: true,
attributeFilter: ['class', 'style', 'data-theme'],
})
}
// ECharts' canvas renderer does not accept OKLCH in every browser. Assigning
// one of our Tailwind tokens to `fillStyle` can silently leave the sentinel
// colour in place, turning a whole chart black. Convert OKLCH ourselves and
// let the canvas normalize older CSS colour formats.
let _hexCanvas: CanvasRenderingContext2D | null = null
export function toCanvasColor(cssColor: string): string {
const value = cssColor.trim()
const match = value.match(
/^oklch\(\s*([+-]?(?:\d+\.?\d*|\.\d+))(%?)\s+([+-]?(?:\d+\.?\d*|\.\d+))\s+([+-]?(?:\d+\.?\d*|\.\d+))(?:deg)?(?:\s*\/\s*([+-]?(?:\d+\.?\d*|\.\d+))(%?))?\s*\)$/i,
)
if (match) {
const lightness = Number(match[1]) / (match[2] === '%' ? 100 : 1)
const chroma = Number(match[3])
const hue = (Number(match[4]) * Math.PI) / 180
const alpha = match[5] == null ? 1 : Number(match[5]) / (match[6] === '%' ? 100 : 1)
const a = chroma * Math.cos(hue)
const b = chroma * Math.sin(hue)
const l = Math.pow(lightness + 0.3963377774 * a + 0.2158037573 * b, 3)
const m = Math.pow(lightness - 0.1055613458 * a - 0.0638541728 * b, 3)
const s = Math.pow(lightness - 0.0894841775 * a - 1.291485548 * b, 3)
const linear = [
4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
]
const rgb = linear.map((channel) => {
const encoded = channel <= 0.0031308 ? 12.92 * channel : 1.055 * Math.pow(channel, 1 / 2.4) - 0.055
return Math.round(Math.min(1, Math.max(0, encoded)) * 255)
})
return alpha < 1 ? `rgba(${rgb.join(', ')}, ${alpha})` : `rgb(${rgb.join(', ')})`
}
if (typeof document === 'undefined') return cssColor
if (!_hexCanvas) {
_hexCanvas = document.createElement('canvas').getContext('2d')
}
if (!_hexCanvas) return cssColor
_hexCanvas.fillStyle = '#010203'
_hexCanvas.fillStyle = value
const normalized = _hexCanvas.fillStyle as string
return normalized === '#010203' && value.toLowerCase() !== '#010203' ? value : normalized
}
// Convert any CSS color (hex, rgb, oklch, color()) + alpha 0..1 to a
// canvas-safe rgba(r,g,b,a). `colorString + '40'` (8-digit hex alpha)
// only works when `colorString` is `#rrggbb`; once tokens resolve to
// oklch() post-hydration the gradient stops break and the canvas paint
// throws every frame. Stay defensive and always return rgba.
export function toRgba(cssColor: string, alpha: number): string {
const normalized = toCanvasColor(cssColor)
if (normalized.startsWith('#') && normalized.length === 7) {
const r = parseInt(normalized.slice(1, 3), 16)
const g = parseInt(normalized.slice(3, 5), 16)
const b = parseInt(normalized.slice(5, 7), 16)
return `rgba(${r},${g},${b},${alpha})`
}
if (normalized.startsWith('rgba(')) {
return normalized.replace(/,\s*[\d.]+\s*\)$/, `,${alpha})`)
}
if (normalized.startsWith('rgb(')) {
return normalized.replace(/^rgb\(/, 'rgba(').replace(/\)$/, `,${alpha})`)
}
// Canvas refused to parse this color -- ship the original string and
// let ECharts complain (better than crashing the paint loop).
return cssColor
}
function resolveVar(name: string, fallback: string): string {
if (typeof window === 'undefined') return fallback
const v = getComputedStyle(document.documentElement).getPropertyValue(name).trim()
if (!v) return fallback
return toCanvasColor(v)
}
// SSR / pre-hydration fallback palette. Hex values picked to roughly
// match the shadcn Neutral defaults in `tailwind.css` so the first paint
// doesn't flicker.
const CHART_FALLBACK = ['#f59e0b', '#14b8a6', '#3b82f6', '#f97316', '#eab308']
export const chartColors: ComputedRef<string[]> = computed(() => {
themeKey.value
return Array.from({ length: 5 }, (_, i) => resolveVar(`--chart-${i + 1}`, CHART_FALLBACK[i]!))
})
export const chartTextColor: ComputedRef<string> = computed(() => {
themeKey.value
return resolveVar('--muted-foreground', '#888888')
})
export const chartAxisColor: ComputedRef<string> = computed(() => {
themeKey.value
return resolveVar('--border', '#e5e5e5')
})
export const chartSplitLineColor: ComputedRef<string> = computed(() => {
themeKey.value
return resolveVar('--border', '#f0f0f0')
})
export const chartTooltipBg: ComputedRef<string> = computed(() => {
themeKey.value
return resolveVar('--popover', 'rgba(255,255,255,0.96)')
})
export const chartTooltipBorder: ComputedRef<string> = computed(() => {
themeKey.value
return resolveVar('--border', '#e5e5e5')
})
export const chartTooltipText: ComputedRef<string> = computed(() => {
themeKey.value
return resolveVar('--popover-foreground', '#333333')
})
export const chartBgColor: ComputedRef<string> = computed(() => {
themeKey.value
return resolveVar('--card', resolveVar('--background', '#ffffff'))
})
// The app's accent, for the one highlighted element on a chart or map — a
// selected route, a focused bar. Category series keep using chartColors.
export const chartAccentColor: ComputedRef<string> = computed(() => {
themeKey.value
return resolveVar('--primary', '#38bdf8')
})
// Out-of-bounds / failure colour for charts that encode good vs bad rather
// than a category — control limits, error series. CSS-level marks can use
// `var(--destructive)` directly; this exists because ECharts needs a resolved
// colour string on the canvas.
export const chartDangerColor: ComputedRef<string> = computed(() => {
themeKey.value
return resolveVar('--destructive', '#dc2626')
})
// Two-level deep merge for ECharts option blocks (xAxis, yAxis, grid,
// tooltip, legend, singleAxis, parallel, etc.). The top-level keys merge
// shallowly, but one nested level (axisLabel, axisLine, splitLine, etc.)
// merges shallowly too so a consumer passing `xAxis: { axisLabel: { fontSize: 9 } }`
// doesn't blow away the wrapper's `color` + base font defaults on the same
// axisLabel block. Arrays + primitives replace outright.
//
// This is the merge strategy the chart wrappers use to fold `props.option`
// onto their computed base option without forcing consumers to spell out
// every default they want to preserve.
export function mergeOptionBlock<T extends Record<string, any>>(base: T, user: Partial<T> | undefined): T {
if (!user) return base
const out: any = { ...base }
for (const k of Object.keys(user)) {
const bv = (base as any)[k]
const uv = (user as any)[k]
if (
bv != null &&
uv != null &&
typeof bv === 'object' &&
typeof uv === 'object' &&
!Array.isArray(bv) &&
!Array.isArray(uv)
) {
out[k] = { ...bv, ...uv }
} else {
out[k] = uv
}
}
return out
}
// Default gauge stoplight: teal (safe) -> amber (warning) -> red (danger).
// Pulled off saturated green and onto teal so the gauge ties back to the
// dashboard palette; red is kept as the universal "limit reached" cue.
// GaugeChart consumes this via its `thresholds` prop default; consumers
// pass their own array to override. Static because gauges have semantic
// meaning (green safe / red danger) that we deliberately don't theme-flip.
export const gaugeThresholds: [number, string][] = [
[0.6, '#14b8a6'],
[0.85, '#f59e0b'],
[1, '#dc2626'],
]
Raw manifest:https://uipkge.dev/r/vue/violin-chart.json
