# Lilt Charts

> React chart cards for dashboards. Pass your rows and name the fields. Each family supplies its own headline, readout, and interaction. Package: `@lilt-ui/charts` 0.13.1 (MIT). Requires React and React DOM 19.

## Install

```bash
npm install @lilt-ui/charts
```

pnpm, yarn, and bun work the same way: `pnpm add @lilt-ui/charts`, `yarn add @lilt-ui/charts`, `bun add @lilt-ui/charts`.

Import the stylesheet once, in the root layout or app entry:

```ts
import '@lilt-ui/charts/styles.css';
```

## Rules

- Every card is a client component. In the Next.js App Router, render cards from a file that starts with `'use client'`.
- Import cards and parts from `@lilt-ui/charts`, and finance cards (candlestick, indicators, price, depth, order book, portfolio) from `@lilt-ui/charts/finance`. Server-safe data helpers (`summarizeRange`, `toChartCsv`, `summarizeFunnelStages`) are also in `@lilt-ui/charts/data`.
- Card titles are optional: omit `title` to render no title. `header={false}` removes the entire header, including headline, delta and period controls. Supply an `aria-label` when your app owns the visible heading. Pass the selected rows through `data` when your app owns period selection.
- Where a card supports legend layouts, `legend={false}` removes the legend without changing its data. `surface="ghost"` only removes the visual frame; it does not hide content. Radial charts keep their centre, pointer inspection, and keyboard inspection when the legend is hidden; Escape clears a pin in every layout.
- Pass rows as they are. `x`, `category`, `value`, and each series `key` name fields of the row type; TypeScript rejects unknown or non-numeric fields.
- `null` is a missing value and draws as a gap; `0` is a measurement. Never replace missing values with zero.
- Format numbers with `valueFormat`, which takes `Intl.NumberFormatOptions`, e.g. `{ style: 'currency', currency: 'USD' }`.
- For rates and levels such as latency or active users, set `aggregate` (`'mean'`, `'last'`, or `'max'`) so the headline is not a meaningless total.
- Give Area, Line, Bar, Combo, and Stat cards the same `sync` name to link their hover; Stat requires `x`. A click pins every linked card (Alt-click or Alt+Enter pins one card only). Area, Line, Bar, and Combo support `target` goal lines and supplied `forecast` rows. Stat uses `target` for its meter or ring and has no `forecast` prop.
- Cards follow shadcn theme variables (`--card`, `--card-foreground`, `--muted-foreground`, `--border`, `--ring`, `--chart-1` to `--chart-5`). Lilt styles sit in the `lilt` cascade layer, so app CSS overrides them.

## Cards by job

Pick the card for the job, then follow its link for examples, data shape, and props. Cards include loading and empty states; legends and inspection controls depend on the family.

### Trends: a value over time

- [Area chart](https://liltui.vercel.app/charts/area): `AreaChartCard`. Trends over time, layered or stacked.
- [Streamgraph](https://liltui.vercel.app/charts/area#streamgraph-api): `StreamgraphCard`. A centered stream shows changing channel composition. Thickness carries the measurement; dots inspect supplied readings. Missing contributions break the whole period. All three loading styles share the skeleton exit, entrance, pointer/keyboard pinning, touch glide, reduced motion, and accessible readings table. Aggregate marks report null as their original datum.
- [Line chart](https://liltui.vercel.app/charts/line): `LineChartCard`. Follow trends and compare changes over time.
- [Combo chart](https://liltui.vercel.app/charts/combo): `ComboChartCard`. Bring amounts and trends together with bars and lines.

### Comparison: categories, before and after, or ranges side by side

- [Bar chart](https://liltui.vercel.app/charts/bar): `BarChartCard`. Compare amounts side by side, stacked, or as shares.
- [Diverging responses](https://liltui.vercel.app/charts/bar#diverging-api): `DivergingBarCard`. Survey counts stack on either side of neutral. Neutral responses split around zero, and missing contributions leave the row incomplete rather than becoming zero. All three loading styles share the skeleton exit, entrance, pointer/keyboard pinning, touch glide, reduced motion, and accessible readings table. Aggregate marks report null as their original datum.
- [Horizontal bar](https://liltui.vercel.app/charts/horizontal-bar): `HorizontalBarChartCard`. Rank categories and see what leads.
- [Mirrored bars](https://liltui.vercel.app/charts/horizontal-bar#mirrored-api): `MirroredBarCard`. Two audience profiles face one another around shared category labels. Both sides use one absolute scale; left-facing bars still represent positive counts. All three loading styles share the skeleton exit, entrance, pointer/keyboard pinning, touch glide, reduced motion, and accessible readings table. Aggregate marks report null as their original datum.
- [Slope chart](https://liltui.vercel.app/charts/slope): `SlopeChartCard`. Compare two periods and see who rose and who fell.
- [Range chart](https://liltui.vercel.app/charts/range): `RangeChartCard`. A low and a high for every observation: floating bars, or error bars around a value.
- [Timeline intervals](https://liltui.vercel.app/charts/range#timeline-api): `TimelineChartCard`. TimelineChartCard draws elapsed time horizontally. Dates, ISO strings, and epoch milliseconds are accepted. Missing endpoints stay unplotted and are counted; reversed intervals are rejected. Overlaps stack without hiding observations. Duration values and summaries are milliseconds, formatted as hours by default; simultaneous intervals add independently.

### Part of a whole: shares of a total, or where a flow goes

- [Radial chart](https://liltui.vercel.app/charts/radial): `RadialChartCard`. Show how each part contributes to the whole.
- [Nested donuts](https://liltui.vercel.app/charts/radial#nesteddonut-api): `NestedDonutCard`. Inner rings show departments; outer rings show their teams. Pinning retains a branch and its ancestors. Leaf-only paths prevent parent totals from being counted twice. All three loading styles share the skeleton exit, entrance, pointer/keyboard pinning, touch glide, reduced motion, and accessible readings table. Aggregate marks report null as their original datum.
- [Treemap](https://liltui.vercel.app/charts/treemap): `TreemapChartCard`. See how each part contributes to the whole, with related parts grouped together.
- [Funnel chart](https://liltui.vercel.app/charts/funnel): `FunnelChartCard`. Follow conversion from the first step to the last.
- [Comparative funnel](https://liltui.vercel.app/charts/funnel#comparativefunnel-api): `ComparativeFunnelCard`. Two cohorts pass through the same stages on one absolute scale. Every stage reports its count and conversion from its own entry cohort. All three loading styles share the skeleton exit, entrance, pointer/keyboard pinning, touch glide, reduced motion, and accessible readings table. Aggregate marks report null as their original datum.
- [Sankey chart](https://liltui.vercel.app/charts/sankey): `SankeyChartCard`. Trace how values flow from one stage to the next.

### KPIs: one headline number, a goal, or a streak

- [Stat cards](https://liltui.vercel.app/charts/stat-cards): `StatCard`. Key metrics at a glance: a value, its change, and a small chart.
- [Progress](https://liltui.vercel.app/charts/progress): `ProgressCard`. See how far you have come toward a goal.
- [Goal pacing](https://liltui.vercel.app/charts/progress#goalpacing-api): `GoalPacingCard`. Actual revenue meets a supplied plan at an explicit cutoff. Later actual values are excluded. Expected progress interpolates only between adjacent known plan readings. All three loading styles share the skeleton exit, entrance, pointer/keyboard pinning, touch glide, reduced motion, and accessible readings table. Aggregate marks report null as their original datum.
- [Milestone progress](https://liltui.vercel.app/charts/progress#milestoneprogress-api): `MilestoneProgressCard`. Named checkpoints keep their measured positions along one track. Completed, current, and upcoming states follow the supplied current value; null means unknown. All three loading styles share the skeleton exit, entrance, pointer/keyboard pinning, touch glide, reduced motion, and accessible readings table. Aggregate marks report null as their original datum.
- [Activity ring](https://liltui.vercel.app/charts/activity-ring): `ActivityRingCard`. A full day of activity, wrapped into a ring.

### Patterns: density, correlation, profiles, or spread

- [Heatmap](https://liltui.vercel.app/charts/heatmap): `HeatmapChartCard`. Spot patterns and busy periods through color.
- [Correlation matrix](https://liltui.vercel.app/charts/heatmap#correlation-api): `CorrelationMatrixCard`. A symmetric Pearson matrix compares each metric with every other metric. Inspection retains both rows and columns and reports the number of complete pairs. Constant values are undefined, not zero correlation. All three loading styles share the skeleton exit, entrance, pointer/keyboard pinning, touch glide, reduced motion, and accessible readings table. Aggregate marks report null as their original datum.
- [Calendar heatmap](https://liltui.vercel.app/charts/heatmap#calendar-api): `CalendarHeatmapCard`. CalendarHeatmapCard lays out one UTC day per cell. Bounds default to the observed dates. Duplicate days are rejected; aggregate them first. Zero stays tinted, absent days are hatched, and unobserved days after today are outlined. Wide calendars scroll on narrow screens. All loading styles fade out through the shared skeleton lifecycle.
- [Scatter chart](https://liltui.vercel.app/charts/scatter): `ScatterChartCard`. Explore relationships between two measurements.
- [Strip and beeswarm](https://liltui.vercel.app/charts/scatter#strip-api): `StripChartCard`. StripChartCard shows individual measurements within categories, with mean as the default headline. Strip uses stable vertical jitter; beeswarm prevents collisions and expands the plot when needed. Both preserve each numeric position. Missing values are counted and remain in the accessible table. Unique labels preserve pin identity across updates.
- [Radar chart](https://liltui.vercel.app/charts/radar): `RadarChartCard`. Compare strengths across several dimensions.
- [Box plot](https://liltui.vercel.app/charts/box-plot): `BoxPlotCard`. Distributions side by side: quartiles, median, whiskers and outliers from raw samples.
- [Violin plot](https://liltui.vercel.app/charts/box-plot#violin-api): `ViolinCard`. A density silhouette reveals each delivery distribution, with measured sample dots and a median readout. Deterministic horizontal offsets separate samples without changing their values. All three loading styles share the skeleton exit, entrance, pointer/keyboard pinning, touch glide, reduced motion, and accessible readings table. Aggregate marks report null as their original datum.

### Cool: spatial charts for calendars, grids, hierarchies, networks, distributions, and cycles; each has its own data contract

- [Chord loom](https://liltui.vercel.app/charts/chord-loom): `ChordLoomCard`. Weighted flows woven through a tilted circular frame, with every ribbon available to inspect.
- [Rank ribbons](https://liltui.vercel.app/charts/rank-ribbons): `RankRibbonsCard`. Follow a leaderboard as its tracks climb, cross, and change places.
- [Event helix](https://liltui.vercel.app/charts/event-helix): `EventHelixCard`. Events climb a coil: recurring times line up while each new cycle rises above the last.
- [Contour islands](https://liltui.vercel.app/charts/contour-islands): `ContourIslandsCard`. Clusters become contour terraces, with the actual observations still visible on their surface.
- [Parallel ribbons](https://liltui.vercel.app/charts/parallel-ribbons): `ParallelRibbonsCard`. Trace a profile through several metrics and find the tradeoffs that one score would hide.
- [Sunburst terraces](https://liltui.vercel.app/charts/sunburst-terraces): `SunburstTerracesCard`. A hierarchy steps outward through circular terraces; each branch owns its share of the ring.
- [Cluster constellation](https://liltui.vercel.app/charts/cluster-constellation): `ClusterConstellationCard`. A spatial network of shaded nodes and curved links, with the inspected node’s neighbours kept in view.
- [Ternary prism](https://liltui.vercel.app/charts/ternary-prism): `TernaryPrismCard`. Three competing ingredients find a position on a triangular floor, while magnitude rises above it.
- [Wind rose](https://liltui.vercel.app/charts/wind-rose): `WindRoseCard`. Compass petals divide a directional distribution into stacked magnitude bands.
- [Marimekko blocks](https://liltui.vercel.app/charts/marimekko-blocks): `MarimekkoBlocksCard`. A segmented floor of equal-depth slabs makes category size and composition visible together.
- [Intersection towers](https://liltui.vercel.app/charts/intersection-towers): `IntersectionTowersCard`. Exclusive set overlaps rise as towers above the membership dots that define them.
- [Horizon folds](https://liltui.vercel.app/charts/horizon-folds): `HorizonFoldsCard`. Signed time series fold into compact bands so many patterns can be read on the same scale.
- [Circle archipelago](https://liltui.vercel.app/charts/circle-archipelago): `CircleArchipelagoCard`. Nested islands of circles reveal a hierarchy while leaf areas keep a common value scale.
- [Helix ribbons](https://liltui.vercel.app/charts/helix-ribbons): `HelixRibbonsCard`. Recurring signals wind upward as ribbons, aligning the same phase across successive cycles.
- [Voxel cloud](https://liltui.vercel.app/charts/voxel-cloud): `VoxelCloudCard`. A genuine XYZ scatter of lit cubes, with camera rotation and slices through the original z values.
- [Arc bridges](https://liltui.vercel.app/charts/arc-bridges): `ArcBridgesCard`. Weighted connections arch over a shared baseline, exposing long jumps and local handoffs.
- [Terrain](https://liltui.vercel.app/charts/terrain): `TerrainCard`. A grid of readings as a lit landscape, so peaks and quiet valleys read at a glance.
- [Hex city](https://liltui.vercel.app/charts/hex-city): `HexCityCard`. Every store, team, or product as a hexagonal tower, so the biggest stands tall in the middle.
- [Voxel waffle](https://liltui.vercel.app/charts/voxel-waffle): `VoxelWaffleCard`. Shares of a whole as a block of cubes you can count, filling from the floor up.
- [Skyline](https://liltui.vercel.app/charts/skyline): `SkylineCard`. A year of daily activity stood up in three dimensions, so streaks and busy weeks read as a skyline.
- [Block city](https://liltui.vercel.app/charts/block-city): `BlockCityCard`. Two categories as a city block: one prism per pair, so the tallest corner of the business stands out.
- [Ridgeline](https://liltui.vercel.app/charts/ridgeline): `RidgelineCard`. Layered ridges receding into depth, so the shape of every row reads at a glance.
- [Spiral year](https://liltui.vercel.app/charts/spiral-year): `SpiralYearCard`. Time as a coil, one turn per year, so the same season lines up across every year.

### Finance: markets and holdings, from `@lilt-ui/charts/finance`

- [Candlestick chart](https://liltui.vercel.app/finance/candlestick): `CandlestickChartCard`. The range and direction of every period at a glance, with trading volume underneath.
- [Indicator chart](https://liltui.vercel.app/finance/indicator): `IndicatorChartCard`. Price on top and oscillators underneath, all reading the same day as you hover.
- [Price chart](https://liltui.vercel.app/finance/price): `PriceChartCard`. The latest price in large type, how far it moved over the period, and the path it took.
- [Depth chart](https://liltui.vercel.app/finance/depth): `DepthChartCard`. How much could trade at each price: buying on the left, selling on the right, and the gap between.
- [Order book](https://liltui.vercel.app/finance/order-book): `OrderBook`. Resting orders level by level, the best prices meeting in the middle.
- [Portfolio chart](https://liltui.vercel.app/finance/portfolio): `PortfolioChartCard`. What an account is worth next to what went into it, and how far it sits below its best.

## Reference

- [Every card with its example, data shape, and props](https://liltui.vercel.app/llms-full.txt)
- [Getting started](https://liltui.vercel.app/guides/installation)
- [API reference](https://liltui.vercel.app/guides/api)