VpChart Vue Component

Relevant source files

The following files were used as context for generating this wiki page:

• src/VpChart.vue
• src/markdown/index.ts
• src/index.ts
• src/config.ts
• README.md

The VpChart component is the core client-side rendering engine of the vitepress-plugin-chartjs library. Its primary purpose is to receive pre-computed chart configurations generated at build-time and instantiate them using Chart.js within a VitePress environment.

The component follows a data-first architecture, where the complexity of parsing YAML/JSON and resolving external URLs is handled during the build process. On the client side, VpChart focuses on performance through lazy loading and seamless integration with VitePress's dark mode.

Sources: src/markdown/index.ts:167-175, README.md:129-135

Component Architecture and Lifecycle

The VpChart component utilizes a canvas element wrapped in a container to render charts. Its lifecycle is heavily integrated with the browser's IntersectionObserver to ensure that Chart.js instances are only created when the component enters the viewport.

Rendering Flow

The following diagram illustrates the lifecycle of the component from mounting to initialization:

The rendering flow ensures efficiency by delaying heavy canvas operations until necessary.
Sources: src/VpChart.vue:87-110, README.md:15-18

Key Component Props

The component accepts three primary props that define its behavior and data:

Prop	Type	Default	Description
id	String	Required	Unique identifier for the canvas element.
data	Object	() => ({})	Pre-parsed Chart.js configuration object resolved at build time.
height	String	'400px'	The CSS height of the chart wrapper.

Sources: src/VpChart.vue:24-41

Theme Integration

The VpChart component reactively adapts to VitePress's dark mode. It watches the isDark state provided by vitepress and updates the chart's visual properties without requiring a full re-render of the data.

This reactive update mechanism allows for smooth transitions between light and dark themes.
Sources: src/VpChart.vue:49-74, src/VpChart.vue:123-125

Theme Color Mapping

The component applies specific colors based on the isDark value:

• Text Color: #e5e7eb (Dark) vs #374151 (Light).
• Grid Color: rgba(255, 255, 255, 0.1) (Dark) vs rgba(0, 0, 0, 0.1) (Light).
• Target Elements: Affects scales.ticks, scales.grid, scales.title, plugins.legend.labels, and plugins.title.

Sources: src/VpChart.vue:53-72

Data and Validation Logic

While the component is simple, the data it receives is strictly validated by the plugin's infrastructure before being injected into the markdown.

Validation Schema

The config.ts file defines the ChartConfigSchema using Zod, which ensures that the data prop passed to VpChart contains at least one dataset and a valid chart type.

Build-Time Processing

Before the VpChart tag is generated, the ChartjsMarkdown plugin processes the configuration:

1. Deep Merge: Merges global defaultOptions with inline chart options.
2. Color Application: Automatically applies a color palette if backgroundColor or borderColor is missing.
3. Plugin Injection: Automatically configures plugins like zoom if enabled in the global plugin configuration.

Sources: src/markdown/index.ts:114-160, src/markdown/index.ts:252-265

Integration and Setup

The component is registered globally through a Vite plugin included in the withChartjs wrapper.

Implementation Details

• Registration: The component registers all registerables from chart.js by default.
• Custom Plugins: Users must register external extensions (like BoxPlot or Treemap) in their theme's enhanceApp to make them available to the VpChart instances.
• SSR Safety: The component includes fallbacks for environments where IntersectionObserver is unavailable, ensuring compatibility with Static Site Generation (SSG).

Sources: src/VpChart.vue:12-19, src/index.ts:31-33, README.md:46-60

Conclusion

The VpChart Vue component serves as a specialized bridge between static markdown data and the dynamic Chart.js library. By offloading data resolution to the build phase and utilizing modern browser APIs like IntersectionObserver, it provides a high-performance charting solution that respects the VitePress design system and dark mode preferences.