bklit-ui

Bklit UI

Composable React chart components (visx + motion) distributed through the @bklit shadcn registry. shadcn add copies the source into the user's project — the user owns that code, and it is the source of truth for props.

Run the shadcn CLI with the project's package runner: npx shadcn@latest, pnpm dlx shadcn@latest, bunx --bun shadcn@latest, or yarn dlx shadcn@latest.

Current Project Context

!`npx shadcn@latest info --json`

If the block above is empty or still shows the command (agents that do not expand ! injections), run npx shadcn@latest info --json yourself before writing code. Use it for framework, aliases (@/…), Tailwind version, and installed components.

• No components.json? Run npx shadcn@latest init first.
• No @bklit in registries? Add "@bklit": "https://ui.bklit.com/r/{name}.json" (see installation.md), or install by URL: npx shadcn@latest add https://ui.bklit.com/r/line-chart.json.

Principles

1. Install before inventing. npx shadcn@latest add @bklit/<item> — never hand-roll SVG charts or reimplement a registry piece.
2. Import from the installed files, never from @bklitui/ui/charts. That is a private monorepo package. Items install to components/charts/<file>.tsx (under src/ when the project uses it); import with the user's alias, e.g. @/components/charts/line-chart. See Imports.
3. Read the installed source. After add, open the files in components/charts/ to confirm prop names and defaults before using them.
4. Compose, don't flatten. Root chart → Grid/Background → series → axes → overlays → ChartTooltip. See composition.md.
5. Theme with tokens. --chart-* variables and chartCssVars, not one-off hex values. See theming.md.

Imports

There is no barrel for component items — import each export from the file that defines it (paths relative to the components/charts/ alias):

Import from	Exports
line-chart	LineChart, Line
area-chart	AreaChart, Area
bar-chart / bar / bar-x-axis / bar-y-axis	BarChart / Bar / BarXAxis / BarYAxis
sparkline	LineSparkline, AreaSparkline, BarSparkline, useSparklineHover
composed-chart / series-bar	ComposedChart / SeriesBar (+ Line, Area from their charts)
scatter-chart	ScatterChart, Scatter
candlestick-chart / candlestick	CandlestickChart / Candlestick
live-line-chart / live-line / live-x-axis / live-y-axis	LiveLineChart / LiveLine / LiveXAxis / LiveYAxis
pie-chart / pie-slice / pie-center	PieChart / PieSlice / PieCenter
ring-chart / ring / ring-center	RingChart / Ring / RingCenter
radar-chart, radar-grid, radar-axis, radar-labels, radar-area	one component each
gauge	Gauge (installed by @bklit/gauge-chart)
funnel-chart	FunnelChart
sunburst-chart, sunburst-segment, sunburst-center, sunburst (buildArcs) …	sunburst parts
heatmap · choropleth · sankey	folder index.ts re-exports every part
grid · x-axis · y-axis · background · reference-area · projection-line · trend-line	Grid · XAxis · YAxis · Background · ReferenceArea · ProjectionLine · TrendLine
band · bollinger	Band · withBollingerBands (installed by @bklit/line-chart, also @bklit/band)
weekends · deadline	Weekends · Deadline (date-axis shading and due-date marker)
tooltip · legend · markers · patterns	folder index.ts (ChartTooltip, Legend*, ChartMarkers, Pattern*)
chart-context	chartCssVars, useChart, TooltipData

import { LineChart, Line } from "@/components/charts/line-chart";
import { Grid } from "@/components/charts/grid";
import { XAxis } from "@/components/charts/x-axis";
import { ChartTooltip } from "@/components/charts/tooltip";
import { chartCssVars } from "@/components/charts/chart-context";

Critical Rules

Composition → composition.md

• Series, axes, overlays, and ChartTooltip are children of the root chart — they read chart context.
• One root per chart. Mixed bars + lines on dates → ComposedChart with SeriesBar (not Bar).
• Grid (or Background) first so series paint above it.
• Live charts use LiveLine, LiveXAxis, LiveYAxis — not Line/XAxis.
• BarChart uses BarXAxis / BarYAxis (band scale), not XAxis.

Theming → theming.md

• --chart-1 … --chart-5 for series; chartCssVars.linePrimary etc. for semantic roles.
• The registry adds missing --chart-* tokens without overwriting the app's existing ones.
• Override tokens in :root / .dark; no dark: classes on chart SVG.

Tooltips → tooltips.md

• ChartTooltip content receives ({ point, index }); rows returns { color, label, value }[].
• indicatorColor is a string or (point) => string.
• Custom crosshairs/indicators use useChart() — never global mouse listeners.

Sparklines (@bklit/sparkline)

• LineSparkline / AreaSparkline / BarSparkline are single elements — data + dataKey, no children. Don't build sparklines from LineChart with hidden axes.
• Omit width to fill the parent; height defaults to 32. color, curve ("monotone" default), strokeWidth, endDot; area fill="gradient" | "solid" + fillOpacity; bar barGap, barRadius.
• No tooltip by design. const hover = useSparklineHover<Row>(), spread hover.sparklineProps (on several sparklines to sync crosshairs), render hover.datum ?? latest yourself. crosshair ("dashed" default, "solid", "gradient", false), dot, interactive={false}. Hover fades the series and re-strokes the hovered segment like the main charts (showHighlight, inactiveOpacity 0.5; bars fade unfocused bars to 0.4). Crosshair and dot spring between points (hoverTransition={false} to snap, springConfig to tune), and new data morphs in over dataTransitionDuration (500ms; 0 snaps). Reduced motion snaps both.
• Enter animation is on (animate, 900ms) and falls back to a fade under reduced motion.

Overlays → overlays.md

• ChartMarkers is a sibling of ChartTooltip; marker hover content goes inside ChartTooltip children.
• ChartBrush has no registry item — don't promise @bklit/brush.
• TrendLine (@bklit/trend-line) fits an existing series' dataKey; place it after that series (line, area, bar incl. horizontal, composed).

Animation and loading → animation.md, loading.md

• Default enter: 1100ms, ease cubic-bezier(0.85, 0, 0.15, 1); bars stagger across ~40% of that.
• Replay with revealSignature or a new key.
• status="loading" on LineChart / AreaChart / BarChart / HeatmapChart — one instance, no component swap.
• Reduced motion is only partially handled internally — see animation.md.

Installation → installation.md

• Let shadcn add install npm deps and @bklit/* registry dependencies; don't pin @visx/* by hand.
• Don't install *-example items into an existing app — they write app/page.tsx.

Catalog

All items install with npx shadcn@latest add @bklit/<item>. For any <item>:

• Docs: https://bklit.com/docs/components/<item> (add-ons live under https://bklit.com/docs/utility/…, e.g. /tooltip, /legend, /axis/y-axis)
• Gallery: https://bklit.com/charts/<item> · Studio (tune props, copy code): https://bklit.com/studio?chart=<item>
• Registry JSON: https://ui.bklit.com/r/<item>.json

Charts

Item	Use when
line-chart	Time series, multi-line trends, markers, dashed tails
area-chart	Trends with filled regions, gradient/pattern fills
sparkline	Tiny inline line / area / bar trends for table cells, KPI and stat cards, dense grids — no axes, grid or tooltip; read the hovered value with useSparklineHover
bar-chart	Category comparisons; grouped, stacked, horizontal, square-column bars
composed-chart	Bars + lines/areas on one date axis, dual Y axes
live-line-chart	Streaming / real-time values ({ time: unixSeconds, value })
scatter-chart	Point clouds over time, multiple series
candlestick-chart	OHLC financial data
profit-loss-line	One series crossing zero, colored by sign (studio slug too)
pie-chart	Part-to-whole slices, optional center stat
ring-chart	Concentric progress rings / donut KPIs
radar-chart	Multi-metric comparison across entities
gauge-chart	Single value 0–100, arc or linear notched track
heatmap-chart	Calendar / contribution grids, binned intensity
funnel-chart	Stage-to-stage conversion
sankey-chart	Flows between nodes
sunburst-chart	Hierarchical part-to-whole with drill-down
choropleth-chart	Geo regions colored by value (world/country maps)

Add-ons (most install automatically as dependencies)

grid, x-axis, y-axis (not pulled in by line/area — add it for a value axis), chart-tooltip, legend, markers, background, patterns, reference-area, projection-line, trend-line (least-squares trend overlay for line/area/bar/composed), band (range / Bollinger band on LineChart; already in line-chart), bar-depth (3D/extruded bars on BarChart), chart-stat-flow (animated stat number used by pie/ring/gauge centers and stat cards). Internal plumbing items (chart-context, chart-animation, chart-series, chart-utils, chart-parent-size, utils, shimmering-text) come in automatically.

Brush: ChartBrush / ChartBrushLayout (docs: /docs/utility/brush) are not in any registry item today. If the user needs brush zoom, say so and point to the docs/source rather than inventing an install command.

Blocks (stat cards; browse at https://bklit.com/blocks)

Item	What
stat-card-area-01	Revenue card: AreaSparkline (gradient), hover-to-read value, NumberFlow, trend badge
stat-card-line-01	Sessions card: LineSparkline with overlaid value, hover-to-read, trend badge
stat-card-choropleth-01	Visitors card: choropleth mini map, trend badge

The area and line cards are built on @bklit/sparkline (installed as a dependency) and use useSparklineHover to swap the headline number for the hovered value. For a sparkline in a table row or a custom card, compose @bklit/sparkline directly instead of installing a block.

Blocks need shadcn card + badge, write sample data under data/, and import from a @/components/charts barrel (components/charts/index.ts) that they create. Installing a second block overwrites that barrel and shared files (stat-card-chart.tsx, stat-card-sparkline-hover.ts, trend-badge.tsx) — merge them by hand.

Workflow

1. Get project context (injection above or npx shadcn@latest info --json); confirm @bklit is configured.
2. Pick the item from the catalog by the story the data tells; ask if unclear.
3. Install: npx shadcn@latest add @bklit/<item> (plus @bklit/y-axis, @bklit/legend, etc. if needed).
4. Read the installed source in components/charts/ (the files the CLI just wrote) — confirm exports, prop names, defaults, and data shape. Prefer it over memory or docs if they disagree.
5. Compose root → grid → series → axes → overlays → tooltip; import from the installed paths with the project alias.
6. Theme with tokens; check light and dark.
7. Point the user to the gallery / Studio URL for variants.

Quick Reference

npx shadcn@latest info --json
npx shadcn@latest add @bklit/line-chart @bklit/y-axis
npx shadcn@latest view @bklit/line-chart     # inspect files before installing

"use client";

import { ChartTooltip } from "@/components/charts/tooltip";
import { Grid } from "@/components/charts/grid";
import { Line, LineChart } from "@/components/charts/line-chart";
import { XAxis } from "@/components/charts/x-axis";

const data = [
  { date: new Date("2025-01-01"), users: 1200, sessions: 1800 },
  { date: new Date("2025-02-01"), users: 1350, sessions: 1950 },
];

export function UsersChart() {
  return (
    <LineChart data={data}>
      <Grid horizontal />
      <Line dataKey="users" stroke="var(--chart-1)" />
      <Line dataKey="sessions" stroke="var(--chart-2)" />
      <XAxis />
      <ChartTooltip />
    </LineChart>
  );
}

Related skills

• bklit-ui-design — design vocabulary and recipes: patterns and textures, squircle / rounded / 3D bars, edge fades, gradients, loading looks, and matching charts to the app's theme. Use it when the request is about how a chart looks.
• bklit-ui-migrate — move Recharts, shadcn ChartContainer / ChartConfig, or TanStack Charts (@tanstack/charts) charts to Bklit equivalents, including tiny charts → sparklines.

Install all three with npx skills add bklit/bklit-ui.

References

• composition.md — structure, data shapes, multi-series
• theming.md — tokens, chartCssVars, dark mode
• tooltips.md — ChartTooltip props, custom content, useChart
• overlays.md — legend, markers, reference area, projection, trend line, background, brush
• animation.md — enter timing, replay, live charts, reduced motion
• loading.md — status, skeletons, loading labels
• installation.md — registry setup, file layout, dependencies