Charts Plugin

A server-side chart data query builder and SVG chart component library for Svelar/SvelteKit. Query your database for chart-ready data with grouping, aggregation, and trend analysis, then render it with zero-dependency SVG chart components.

Package: @beeblock/svelar-charts

Install:

npx svelar plugin:install @beeblock/svelar-charts

Imports:

// Plugin registration
import { SvelarChartsPlugin } from '@beeblock/svelar-charts/server';

// Core API
import { ChartQuery, ChartDataBuilder } from '@beeblock/svelar-charts';

// Server-side (controller)
import { ChartController } from '@beeblock/svelar-charts/server';

// UI components
import { BarChart, LineChart, PieChart, DoughnutChart, AreaChart, SparkLine, StatCard, ChartCanvas, Tooltip, Legend } from '@beeblock/svelar-charts/ui';

// Types
import type { ChartData, ChartDataset, TrendChartData, TrendDirection, DateGrouping, BaseChartProps, BarChartProps, LineChartProps, PieChartProps, DoughnutChartProps, AreaChartProps, SparkLineProps, StatCardProps, SvelarChartsConfig } from '@beeblock/svelar-charts';

Quick Start

1. Register the Plugin

// src/lib/plugins.ts
import { SvelarChartsPlugin } from '@beeblock/svelar-charts/server';

export const chartsPlugin = new SvelarChartsPlugin({
  prefix: '/api',
  defaultColors: ['#3B82F6', '#10B981', '#F59E0B', '#EF4444', '#8B5CF6'],
  animate: true,
});

2. Query Data and Render a Chart

// src/routes/dashboard/+page.server.ts
import { ChartQuery } from '@beeblock/svelar-charts';

export async function load() {
  const usersPerMonth = await ChartQuery.table('users')
    .count()
    .groupBy('month', 'created_at')
    .period('2026-01-01', '2026-12-31')
    .label('New Users')
    .get();

  return { usersPerMonth };
}

<!-- src/routes/dashboard/+page.svelte -->
<script lang="ts">
  import { BarChart } from '@beeblock/svelar-charts/ui';

  interface Props {
    data: { usersPerMonth: import('@beeblock/svelar-charts').ChartData };
  }
  let { data }: Props = $props();
</script>

<BarChart data={data.usersPerMonth} height={300} />

Configuration

The SvelarChartsPlugin constructor accepts:

Default color palette: #3B82F6 (blue), #10B981 (emerald), #F59E0B (amber), #EF4444 (red), #8B5CF6 (violet), #EC4899 (pink), #06B6D4 (cyan), #F97316 (orange), #14B8A6 (teal), #6366F1 (indigo).

Core API

ChartQuery

A fluent query builder that generates chart-ready data from database tables. Uses the Svelar Connection under the hood.

import { ChartQuery } from '@beeblock/svelar-charts';

Factory:

const query = ChartQuery.table('orders');

Fluent methods:

Examples:

// Count users by role
const usersByRole = await ChartQuery.table('users')
  .count()
  .groupBy('role')
  .label('Users')
  .get();
// => { labels: ['admin', 'editor', 'user'], datasets: [{ label: 'Users', data: [5, 12, 89] }] }

// Monthly revenue over a year
const revenue = await ChartQuery.table('orders')
  .sum('total')
  .groupBy('month', 'created_at')
  .period('2026-01-01', '2026-12-31')
  .where('status', 'completed')
  .label('Revenue')
  .get();

// Trend: new users in the last 30 days vs. the previous 30 days
const trend = await ChartQuery.table('users')
  .count()
  .label('New Users')
  .trend('day', 30);
// => { labels, datasets, change: 15.2, direction: 'up', currentValue: 142, previousValue: 123 }

Date grouping intervals (DateGrouping):

ChartData

The standard data structure consumed by all chart components:

interface ChartData {
  labels: string[];
  datasets: ChartDataset[];
}

interface ChartDataset {
  label?: string;
  data: number[];
  color?: string;
  backgroundColor?: string;
  borderColor?: string;
  borderWidth?: number;
  hidden?: boolean;
}

TrendChartData

Extended ChartData with period comparison info:

interface TrendChartData extends ChartData {
  change: number;          // percentage change (e.g. 15.2 or -8.3)
  direction: 'up' | 'down' | 'flat';
  currentValue: number;    // total for the current period
  previousValue: number;   // total for the previous period
}

ChartDataBuilder

Manually construct ChartData when you already have the data:

import { ChartDataBuilder } from '@beeblock/svelar-charts';

// Fluent builder
const data = new ChartDataBuilder()
  .labels(['Jan', 'Feb', 'Mar', 'Apr'])
  .dataset('Revenue', [1200, 1800, 2400, 2100], { color: '#3B82F6' })
  .dataset('Expenses', [800, 900, 1100, 950], { color: '#EF4444' })
  .build();

// From a key-value map
const pie = ChartDataBuilder.fromMap(
  { Chrome: 65, Firefox: 15, Safari: 12, Other: 8 },
  'Browser Share',
);

// From an array of objects
const bar = ChartDataBuilder.fromArray(
  products,
  'name',    // label key
  'sales',   // value key
  'Product Sales',
);

Server-Side

ChartController

Provides static methods for serving chart data as JSON:

// src/routes/api/charts/users/+server.ts
import { ChartController } from '@beeblock/svelar-charts/server';
import { ChartQuery } from '@beeblock/svelar-charts';

// Serve a pre-built query
export const GET = async (event) => {
  const query = ChartQuery.table('users')
    .count()
    .groupBy('month', 'created_at')
    .period('2026-01-01', '2026-12-31')
    .label('Users');

  return ChartController.serve(query);
};

// Serve trend data
export const GET = async (event) => {
  const query = ChartQuery.table('orders')
    .sum('total')
    .label('Revenue');

  return ChartController.serveTrend(query, 'month', 90);
};

// Generic handler with dynamic query params
export const GET = async (event) => {
  return ChartController.handle(event, (query, params) => {
    const groupBy = params.get('group_by') || 'month';
    return query.count().groupBy(groupBy, 'created_at');
  });
};

UI Components

All chart components render pure SVG with no external dependencies.

BarChart

<script lang="ts">
  import { BarChart } from '@beeblock/svelar-charts/ui';
</script>

<BarChart
  data={chartData}
  height={300}
  width={600}
  horizontal={false}
  stacked={false}
  barRadius={4}
  barGap={4}
  showValues={false}
  showLegend={true}
  animate={true}
/>

LineChart

<script lang="ts">
  import { LineChart } from '@beeblock/svelar-charts/ui';
</script>

<LineChart
  data={chartData}
  height={300}
  smooth={false}
  showArea={false}
  showDots={true}
  dotRadius={4}
  strokeWidth={2}
  showLegend={true}
/>

PieChart

<PieChart
  data={chartData}
  size={300}
  showLabels={true}
  showPercentages={true}
  donut={false}
  donutWidth={60}
/>

DoughnutChart

<DoughnutChart
  data={chartData}
  size={300}
  ringWidth={60}
  showLabels={true}
  showPercentages={true}
  centerLabel="Total"
  centerValue="1,234"
/>

AreaChart

<AreaChart
  data={chartData}
  height={300}
  gradient={true}
  smooth={true}
  fillOpacity={0.3}
  showDots={true}
/>

SparkLine

A minimal inline chart for dashboards and tables:

<SparkLine
  data={[10, 15, 8, 22, 18, 25, 30]}
  width={120}
  height={32}
  color="#3B82F6"
  strokeWidth={1.5}
  showEndDot={true}
/>

StatCard

A stat card with title, value, trend indicator, and optional sparkline:

<StatCard
  title="Total Revenue"
  value="$12,345"
  change={15.2}
  trend="up"
  sparkData={[100, 120, 115, 140, 155, 170]}
  sparkColor="#10B981"
/>

Full Working Example

// src/routes/dashboard/+page.server.ts
import { ChartQuery } from '@beeblock/svelar-charts';

export async function load() {
  const usersTrend = await ChartQuery.table('users')
    .count()
    .label('New Users')
    .trend('month', 365);

  const revenueByMonth = await ChartQuery.table('orders')
    .sum('total')
    .groupBy('month', 'created_at')
    .period('2026-01-01', '2026-12-31')
    .where('status', 'completed')
    .label('Revenue')
    .get();

  const usersByRole = await ChartQuery.table('users')
    .count()
    .groupBy('role')
    .label('Users by Role')
    .get();

  return { usersTrend, revenueByMonth, usersByRole };
}

<!-- src/routes/dashboard/+page.svelte -->
<script lang="ts">
  import { StatCard, BarChart, PieChart } from '@beeblock/svelar-charts/ui';

  interface Props {
    data: {
      usersTrend: import('@beeblock/svelar-charts').TrendChartData;
      revenueByMonth: import('@beeblock/svelar-charts').ChartData;
      usersByRole: import('@beeblock/svelar-charts').ChartData;
    };
  }
  let { data }: Props = $props();
</script>

<div class="dashboard-grid">
  <StatCard
    title="New Users"
    value={String(data.usersTrend.currentValue)}
    change={data.usersTrend.change}
    trend={data.usersTrend.direction}
    sparkData={data.usersTrend.datasets[0]?.data}
    sparkColor="#3B82F6"
  />

  <BarChart data={data.revenueByMonth} height={350} showValues={true} />

  <PieChart data={data.usersByRole} size={300} showLabels={true} showPercentages={true} />
</div>

// src/routes/api/charts/revenue/+server.ts
import { ChartController } from '@beeblock/svelar-charts/server';
import { ChartQuery } from '@beeblock/svelar-charts';

export const GET = async (event) => {
  const query = ChartQuery.table('orders')
    .sum('total')
    .groupBy('month', 'created_at')
    .period('2026-01-01', '2026-12-31')
    .where('status', 'completed')
    .label('Revenue');

  return ChartController.serve(query);
};