vue-chrts

repository·main·Indexed 19 days ago

https://github.com/dennisadriaans/vue-chrts

A Vue 3 charting library inspired by Tremor and built on top of Unovis, providing responsive and customizable charts for Vue and Nuxt applications. It includes a Nuxt module (nuxt-charts) for auto-importing components and types. Available charts include AreaChart, BarChart, LineChart, DonutChart, BubbleChart, RadarChart, RadialBarChart, FunnelChart, CandlestickChart, StatusTrackerChart, and DualChart.

Tokens
21.1K
Snippets
64
Records
93
Agent score
63%

What's inside vue-chrts

  1. Understand nuxt-charts e2e testing modes

    main

    The e2e suite uses two distinct modes to ensure module stability across different environments:

    1. dev mode: Exercises the module's optimizeDeps/transpile setup, which specifically targets Vite pre-bundling behavior.
    2. prod mode: Exercises the nuxt build output. This is critical because the production module graph is different and can fail due to bad externals or missing SSR dependencies even if the dev mode passes.

    A successful release requires both modes to pass.

  2. Install nuxt-charts for Nuxt projects

    main

    To use the charts module in a Nuxt application, install the nuxt-charts package using your preferred package manager and then register it in your nuxt.config.ts file.

    # npm
    npm install nuxt-charts
    
    # yarn
    yarn add nuxt-charts
    
    # pnpm
    pnpm add nuxt-charts

    Add module to your nuxt.config.ts

    export default defineNuxtConfig({
      modules: ["nuxt-charts"]
    });
  3. Migrating from nuxt-charts v2 to v3

    main

    If you are upgrading from v2 to v3, be aware of the following changes:

    • Removed Components: GanttChart, DagreGraph, and Maps have been removed in v3 as they were Unovis/d3-geo specific and lack vccs equivalents.
    • Deferred Components: SankeyChart is deferred until the underlying vccs library supports it. DualChart is planned for v3.1.
    • Prop Changes:
      • xExplicitTicks and yExplicitTicks are now handled via the axis.ticks property.
      • minMaxTicksOnly is now handled via interval="preserveStartEnd".

    If your project requires specialty charts (maps, gantt, dual, sankey, dagre), you should remain on nuxt-charts@2.

  4. Run nuxt-charts e2e tests

    main

    The end-to-end (e2e) tests verify that every chart type registered by the module renders correctly in a browser via the Nuxt module against a fresh build of vue-chrts.

    Using pnpm scripts

    Use these commands for standard testing workflows:

    • pnpm test:e2e:all: Performs a fresh build and runs both dev and prod modes. This is the recommended pre-release gate.
    • pnpm test:e2e: Runs the dev server mode only.
    • pnpm test:e2e:prod: Runs the prod (production build) mode only.

    Using the runner script directly

    For more granular control, use ./scripts/run-e2e.sh:

    • ./scripts/run-e2e.sh: Equivalent to test:e2e:all.
    • ./scripts/run-e2e.sh --dev: Runs in dev mode only.
    • ./scripts/run-e2e.sh --skip-build: Reuses the existing vue-chrts dist folder instead of rebuilding.
    • ./scripts/run-e2e.sh --grep <pattern>: Passes arguments through to Playwright (e.g., --grep sankey).

    Understanding results

    The runner outputs a single JSON line containing the status and summary. If a failure occurs, the JSON includes a log path. It is recommended to read the log file rather than re-running the tests immediately.

    pnpm test:e2e:all      # fresh build, dev + prod
    pnpm test:e2e          # dev server only
    pnpm test:e2e:prod     # production build only
  5. Install vue-chrts for Vue.js projects

    main

    To use the charts in a standard Vue 3 application, install the vue-chrts package and import the specific chart components you need directly into your components.

    # npm
    npm install vue-chrts
    
    # yarn
    yarn add vue-chrts
    
    # pnpm
    pnpm add vue-chrts

    import component

    import { LineChart } from 'vue-chrts';
  6. Use the DualChart component

    main

    The DualChart component overlays line charts on top of bar charts, allowing you to visualize different metrics simultaneously (e.g., actuals vs. targets). It supports multiple bar series (grouped or stacked) and multiple line series. It is responsive and includes interactive tooltips and customizable legends.

    <script setup lang="ts">
    import { DualChart, LegendPosition } from 'vue-charts';
    
    type DataItem = {
      month: string;
      revenue: number;
      costs: number;
      profit: number;
    };
    
    const data: DataItem[] = [
      { month: "January", revenue: 45000, costs: 30000, profit: 15000 },
      { month: "February", revenue: 52000, costs: 35000, profit: 17000 },
    ];
    
    const barCategories = {
      revenue: { name: "Revenue", color: "#3b82f6" },
      costs: { name: "Costs", color: "#ef4444" },
    };
    
    const lineCategories = {
      profit: { name: "Profit", color: "#22c55e" },
    };
    </script>
    
    <template>
      <DualChart
        :data="data"
        :bar-categories="barCategories"
        :line-categories="lineCategories"
        :bar-y-axis="['revenue', 'costs']"
        :line-y-axis="['profit']"
        :height="300"
        :x-formatter="(tick: number): string => data[tick]?.month || ''"
        :tooltip-title-formatter="(d: DataItem) => d.month"
        y-label="Amount ($)"
      />
    </template>
  7. Avoid type clashes when using nuxt-charts-legacy and nuxt-charts-next together

    main

    If your project uses both nuxt-charts-legacy and nuxt-charts-next, you must disable sharedImports in the legacy module configuration. This prevents the legacy module from auto-importing shared enums and types that are already managed by the nuxt-charts-next (v3) module, which avoids duplicate auto-imports and nominal enum type clashes.

    Map-specific helpers (such as getMap, getPin, geoMercator, MapRegion, and MapPin) are always auto-imported when autoImports is enabled and cannot be disabled via this setting.

  8. Configure nuxt-charts module options

    main

    You can customize how nuxt-charts behaves in your Nuxt application via the nuxtCharts key in nuxt.config.ts.

    export default defineNuxtConfig({
      modules: ["nuxt-charts"],
      nuxtCharts: {
        prefix: "",        // prefix component names, e.g. "V" -> <VBarChart>
        global: true,      // register globally (no import needed)
        autoImports: true, // auto-import enums and prop types
        include: [],       // [] = all; or a subset, e.g. ["BarChart", "LineChart"]
      },
    })
  9. Configure Cartesian charts (Area, Line, Bar, Bubble)

    main

    Cartesian charts share a common set of base properties for managing axes, legends, tooltips, and grids. Use CartesianChartBaseProps<T> to configure these shared elements.

    Common Props

    • data: Array of type T representing the data points.
    • categories: A Record<string, BulletLegendItemInterface> mapping category keys to their legend representation (label and color).
    • xLabel / yLabel: Optional axis labels.
    • xFormatter / yFormatter: Functions to format axis ticks.
    • hideLegend / hideTooltip: Boolean flags to toggle UI elements.
    • legendPosition: Position of the legend.
    • xGridLine / yGridLine: Toggle horizontal/vertical grid lines.
    • xDomain / yDomain: Fixed axis ranges as [min, max].
    • yAxes: A Record<AxisId, YAxisConfig> for adding multiple independent Y-axes. To use a specific axis, reference its ID in a category's yAxis field.
    • syncId: A string used to synchronize tooltips and hover states across multiple charts.
    • theme: Per-chart appearance overrides for grid, axis, legend, etc.
    // Example of configuring multiple Y-axes
    const categories = {
      temperature: { name: "Temp", yAxis: "temp" },
      humidity: { name: "Humidity", yAxis: "pct" },
    };
    
    const yAxes = {
      temp: { orientation: "left", label: "°C" },
      pct: { orientation: "right", label: "%" },
    };