Documentation / @ripl/vue-charts

@ripl/vue-charts

Declarative Vue 3 components for Ripl's 25 chart types.

Props are the chart's options, and changing one updates the chart in place rather than rebuilding it.

Installation

npm install @ripl/vue-charts

@ripl/vue and @ripl/charts arrive as dependencies. vue (3.5 or later) is a peer dependency.

Quick start

import {
    createRiplCharts,
} from '@ripl/vue-charts';

createApp(App).use(createRiplCharts()).mount('#app');

createRiplCharts() registers the core Ripl components too, so a chart can share a page, or even a context, with hand-drawn elements.

<template>
    <ripl-bar-chart
        :data="data"
        :series="series"
        key-by="month"
        title="Monthly breakdown"
        :legend="true"
        @barclick="onBarClick"
    />
</template>

Props are options

Every prop maps to a top-level chart option, the furniture included: axis, grid, legend, tooltip, crosshair, annotations, navigator, title, animation, theme and padding.

• An unbound prop is never written, so the chart keeps its own default.
• A bound object replaces the whole option. The merge is shallow and top-level, so :axis must be passed complete rather than partially.
• Props are compared by identity, so hoist object and array bindings to a computed.

keyBy, not key

Vue reserves key as the vnode key, so a chart's key option is bound as key-by and renamed on the way in.

Events

Listener props come from the events each chart declares, so they match the imperative API exactly: @barclick, @segmententer, @nodeclick. A chart subscribes only to an event you actually bind.

Sharing a context

A chart builds its own scene and renderer, so it is a peer of <ripl-context> rather than something nested in a <ripl-scene>. Given one, it draws into it:

<template>
    <ripl-context style="width: 640px; height: 360px">
        <ripl-bar-chart :data="data" :series="series" key-by="month" />
    </ripl-context>
</template>

Unmounting then leaves the context alone; a standalone chart destroys the surface it made.

Compositions

import {
    useRiplChart,
} from '@ripl/vue-charts';

const chart = useRiplChart();

A template ref on any chart component resolves to the chart itself, which is how you reach the imperative APIs with no declarative equivalent: chart.navigator, and push() / clear() on a realtime chart.

Documentation

Full documentation lives at ripl.run.

License

MIT

Interfaces

Interface	Description
RiplChartDefinition	Describes one chart to wrap as a component.

Type Aliases

Type Alias	Description
RiplAnyChart	Any chart, whatever its option and event types.
RiplChartListener	A forwarded chart event listener. Receives the event's payload directly, with the underlying Event — carrying target, timestamp and stopPropagation — as a second argument.
RiplChartListeners	The listener props a chart component accepts, derived from the events the chart declares.
RiplChartProps	A chart's options as component props, with any option whose name Vue reserves renamed.

Variables

Variable	Description
BASE_CHART_OPTION_KEYS	The options every chart accepts, whatever its type.
CHART_OPTION_KEYS	The options specific to each chart type, on top of BASE_CHART_OPTION_KEYS.
RIPL_CHART	Injection key for the chart a subtree belongs to.
RiplArcDiagramChart	An arc diagram: nodes on a line, links drawn as arcs above it.
RiplAreaChart	An area chart: one or more filled series over a shared category axis.
RiplBarChart	A bar chart, vertical or horizontal, grouped or stacked.
RiplBoxPlotChart	A box plot showing the quartiles and outliers of each category.
RiplChordChart	A chord diagram of flows between groups arranged around a circle.
RiplContext	Creates a Ripl rendering context and provides it to its subtree, mounting the canvas into its own root element.
RiplForceDirectedChart	A force-directed graph, laid out by simulated attraction and repulsion.
RiplFunnelChart	A funnel chart of values narrowing through successive stages.
RiplGanttChart	A gantt chart of tasks across time, with optional dependencies and progress.
RiplGaugeChart	A gauge showing a single value within a range.
RiplHeatmapChart	A heatmap of values across two categorical axes.
RiplHistogramChart	A histogram binning a continuous value into buckets.
RiplLineChart	A line chart: one or more series over a shared category axis.
RiplPackedCircleChart	A packed circle chart sizing each datum by value.
RiplPieChart	A pie or donut chart of values as angular segments.
RiplPolarAreaChart	A polar area chart: segments of equal angle and value-driven radius.
RiplPolarScatterChart	A polar scatter chart plotting points by angle and radius.
RiplRadarChart	A radar chart comparing series across shared categories.
RiplRadialBarChart	A radial bar chart of values as concentric arcs.
RiplRealtimeChart	A realtime chart streaming values through a fixed time window.
RiplSankeyChart	A sankey diagram of flows between nodes, sized by value.
RiplScatterChart	A scatter chart plotting points by two continuous values.
RiplStockChart	A stock chart of candlestick or OHLC bars, with optional volume.
RiplSunburstChart	A sunburst chart of a hierarchy as concentric rings.
RiplTreemapChart	A treemap of a hierarchy as nested rectangles.
RiplTrendChart	A trend chart mixing line, area and bar series on shared axes.

Functions

Function	Description
createRiplCharts	Creates the Vue plugin that registers every Ripl chart component globally, along with the core components from @ripl/vue — so a chart can share a <ripl-context> with hand-drawn elements.
defineRiplChart	Builds a declarative component for a Ripl chart.
useRiplChart	Returns the chart provided by the nearest chart component.
useRiplContext	Returns the rendering context provided by the nearest context component.