Chart

If your project doesn't have Wisty UI's theme yet, add it once with npx shadcn@latest add @wisty/cosmos. Until then, components keep shadcn's default look. Installation has the details.

Every chart is Recharts composed inside ChartContainer, with a config that names each series and gives it a color.

The tooltip and legend read their labels and colors from the config. To format tooltip values, map payload as below, so each row keeps its indicator and name.

Each config key gets --color-<key> inside the chart. Which fields are keys:

• A series key, the dataKey of a measure like amount, is a config key.
• In a donut or funnel, nameKey picks a row field, like source. That field's values (Web, Partner Referral) are config keys.
• A category axis's field, like stage above, needs no entry. Its values are the tick labels.
• A key can be a value straight from the data, spaces and punctuation included. Paint it with chartColor(key), which returns the var(--color-<key>) the chart defines for it, escaped: fill={chartColor(row.source)}.
• When a tooltip looks up config[row.segment].label, as the Scatter plot example does, type the field as the config's keys. Rows from a query come as string, so check each value before you build them.

A config entry's icon, an icon component, takes the place of that series' swatch in the legend and its indicator in the tooltip, in the muted text color. hideIcon on ChartLegendContent brings the legend's swatches back.

From a report or query, take the keys from the grouping, the labels from its display values and the colors by position. Keep the four largest groups and add the rest into one "Others" row.

SLDS 2 has no chart stylesheet or blueprint. The Charts guidelines set the look, and the tokens set the values.

• Series colors --chart-1 to --chart-6 are Lightning's default chart palette, in hue and tint pairs: blue, light blue, purple, light purple, teal, light teal. Dark mode takes the darker set a Lightning dashboard draws there.
• data-chart-palette on any element inside the theme root switches the charts in it to Salesforce's other dashboard palettes, with the names a dashboard's properties use. default and color-safe are categorical, with distinct hues. bluegrass, sunrise, water and watermelon are sequential, light to dark, for ordered buckets.
• The tooltip is SLDS's hover tooltip on the popover surface. Legend swatches and tooltip dots are SLDS's legend dots.
• The donut is SLDS's thin ring, starting at 12 o'clock and running clockwise. The funnel is SLDS's: a stacked column, each stage as tall as its value, clipped to a taper.
• A chart sits on a card, as a Lightning dashboard component does: the card's title, description and footer play its title, subtitle and footer. The title names what's measured ("Sales by account"), never the chart type; the description holds the period and the unit.

Known gaps:

• Compact numbers print "$620K". Salesforce prints a lowercase "k".
• Recharts' legend can't show values beside each entry or a size scale. Use Chart legend in HTML beside the chart.
• Not drawn: treemap, heatmap, map, sankey and origami. When not to use lists what to draw instead.

Each chart is one tab stop.

• On horizontal bars (layout="vertical"), ArrowLeft moves down the list and ArrowRight moves up. ArrowUp, ArrowDown, Home and End do nothing.
• The arrows walk only the first Scatter of a chart, so put every row in one.
• The funnel is one point to Recharts. Focus shows the first stage and the arrows don't move, so draw each stage's count on its band and name each stage with its count in an HTML legend, as the Funnel chart example does.
• The keys can't choose a mark. To drill into the records behind a bar, take the click from Bar onClick and give keyboard users a second control after the chart, such as a select of the same categories, as the Bar chart with drill-down example does.

• Name every chart from visible text: aria-labelledby on the chart root, pointing at the CardTitle of the card it sits on. Don't use the title prop, which draws an SVG title that browsers may show on hover.
• Moving with the arrow keys announces nothing. Put the key numbers in HTML near the chart, as a table or a sentence, when exact values matter.
• A Pie adds a second tab stop unless it has rootTabIndex={-1}.
• Color never carries meaning alone. Label the series, dash targets, give changes a sign, and name a scatter's group in its tooltip.
• The palettes are Salesforce's as published. The lighter tints sit under 3:1 on white, so label them and check the series you draw against your background.

• Series animate in on mount and when the data changes. Keep the chart mounted and its series keys stable, so it moves from the old values to the new; don't key a chart by period.
• A period switch keeps one value axis for every period: getNiceTickValues over all the periods' rows, passed as ticks and as the top of domain. Marks then move against a steady scale, and periods compare honestly; Recharts doesn't animate an axis that rescales.
• Bars match old to new by their category with animationMatchBy={matchByDataKey("size")}, so a category that comes or goes grows in or shrinks out instead of the bars beside it shifting values.
• Lines, areas and donuts take animationDuration={800} and animationEasing="cubic-bezier(0.42,0,0.58,1)", and a Pie also takes animationBegin={0}. Recharts' named easings don't match CSS: its ease-in-out is CSS's ease-out.
• The tooltip fades in and moves between points in 0.1s.
• A leaving stacked column collapses as one block, and each donut slice slides from its old angles to its new ones, so a slice that changes rank slides past its neighbour and a leaving slice sweeps shut where it was, each through the example's animationInterpolateFn; Recharts' defaults split the stack into slivers and snap the ring to the new order.
• A waterfall's steps grow from their own start, not from zero, through the example's animationInterpolateFn; a step that leaves drops its label at once.
• With reduced motion, series and tooltip don't animate.

• ChartContainer fills its width at 16:9 and redraws on resize. Inside a flex parent it has no width of its own, so give it w-full.
• Under 24rem, as in a third of a dashboard, 16:9 leaves too little plot. Put @container on the figure or card and @max-sm:aspect-square on ChartContainer.
• A donut with its legend on the right takes mx-auto aspect-[3/2] w-full max-w-md; with the legend below, mx-auto aspect-square w-full max-w-72. A funnel takes aspect-[4/3] w-full beside its legend, which moves under it in a narrow card.
• A legend on the right needs about 400px. In a narrow card, put it below: a legend is a prop, so the donut example reads useChartWidth() and moves it under 384px.
• On an ordered axis (months, size buckets), thin crowded ticks evenly with interval="equidistantPreserveStart". Never thin names that aren't ordered, like accounts: interval={0} and a tick that wraps them, as the bar chart's does. When every name must show, as a waterfall's steps must, use interval={0} and a tick that wraps names under their column and turns them 45° below about 56px a column.

• Each chart is one SVG, and Recharts adds about 100 kB gzipped to the bundle.
• Hundreds of points draw fine. Lightning turns hover off above 200 points; aggregate or bin the data before that.
• Keep data and the config outside the component or in state, so Recharts doesn't animate the same series again on every render.

Rows and color

• Rows hold raw numbers (620000, never 620 "in thousands"), in the order drawn: largest first for comparisons and shares, buckets in their own order.
• Picklist values are data, written as Salesforce labels them: "Closed Won", "Proposal/Price Quote", "Partner Referral". A measure's name is sentence case: "Closed won" for the amount.
• One config per dashboard, satisfies ChartConfig, with color or theme per series. Never a colors array.
• Colors go --chart-1 onward in order, as Lightning's dashboards draw them. The values of one grouping (stages, products, segments) take the palette in order, so three stages are blue, light blue and purple. Two different measures take --chart-1 and --chart-3; the same measure in an earlier period takes its tint, --chart-2.
• The slice or bar that folds the small groups ("Others") takes --chart-other, a neutral, and goes last.
• Paint with fill="var(--color-<key>)", or chartColor(key) for a key from data, never Cell or a hex value. Choose data-chart-palette per dashboard, not per chart.
• --success and --destructive only for marks that mean good or bad, with a sign or a word.
• At most four lines, five slices and about 12 bar categories.

Axes and marks

• tickLine={false} axisLine={false} on every axis, tickMargin={8} on category axes, width="auto" on Y axes. Value axes start at zero.
• margin={{ top: 12 }} at least, or Recharts pushes the top tick's label below its gridline to keep it inside the chart.
• Horizontal bars and dot plots put the value axis on top and use CartesianGrid horizontal={false}; every other chart uses vertical={false}.
• Title an axis only when the card's description doesn't carry its unit. A rotated title takes textAnchor: "middle" so it centers on the axis. Two units get two titled YAxis, the second on the right; never three.
• Lines are type="linear" and strokeWidth={2}. One series over time is an Area with fillOpacity={0.2} and dots; two to four are Lines with dot={false}.
• cursor={false} on scatter, dot plot, donut and funnel.
• A waterfall shows a start, the steps and an end, never the parts of one number. Its rows are signed changes and totals; a stated total that doesn't match the steps before it adds a "Not accounted for" step, never a corrected one.
• A waterfall's steps go rises first, then falls, each largest first, or in time order, and in the same order in every period, so a filter moves them instead of shuffling them. Keep to about 10 steps and fold the smallest into "Other". One waterfall per card: they don't work as small multiples.

Legend, tooltip and labels

• No legend for one series. Otherwise <ChartLegend itemSorter={null} content={<ChartLegendContent />} /> below the chart, since Recharts sorts by name without it. Every legend entry must be a config key, or it shows a swatch with no text.
• Every legend reads swatch, then name. A legend of a field's values (stages, products, sources) starts with the field's name in muted text, as Lightning titles its legends; a legend of measures (Sales, Profit) has none. Put it in the legend's content, before ChartLegendContent.
• A donut's or funnel's legend sits on its right, top-aligned; every other chart's sits below. In a narrow card, every legend goes below.
• A scatter with groups builds its legend from the groups: content={() => <ChartLegendContent payload={legend} />}.
• Charts whose marks are blocks, like the funnel, take data-chart-swatch="square" on ChartContainer, so the legend and tooltip swatches match the marks.
• Format with a fixed locale: compact for ticks and labels ("$620K"), full for tooltips. Pass compact.format, never the formatter object. formatter on ChartTooltipContent replaces the whole row.
• A fixed target is a dashed ReferenceLine with ifOverflow="extendDomain", or a target above the data disappears. Label it where no bar crosses the line. A target that changes by period is a dashed series. Only targets and forecasts are dashed.
• Value labels sit outside the bar: <LabelList className="fill-foreground" /> at right or top. When every bar has one, hide the value axis and the grid. A waterfall keeps both, since its labels hide in a narrow card.
• A donut's total is a Label with position="center" whose content centers on x + width / 2 and y + height / 2. A "cx" in viewBox check draws nothing.

Names and states

• Keep the chart's box while rows load: aria-busy="true" on the card, a Skeleton at the chart's aspect ratio and an sr-only "Loading chart". Never empty axes or fake series.
• No rows is an Empty in the same box that says what's missing and what to change. An error is the same Empty with the message and a Retry button.
• Never pass activeShape.