Forecast Band

Installation & usage

npm i @youj/react

For an app already set up with npx @youj/cli init, which installs the peers (@youj/core, @youj/motion, motion and Base UI) and wires the provider. New app? Start at Installation.

Use a forecast band for a total that only grows through a period (cloud spend, ad spend, API calls against a quota) when the question is where it lands and when it crosses the line. Spend so far is a solid ink line over a faint wash. From today the forecast carries on as a dashed line in its tone, inside its likely range, over a hatched projected area: solid for what's settled, hatched for what isn't, as in the Hatched Bar. The budget is a dashed line. If the forecast crosses it, the stretch above the line is hatched in danger and a marker lands on the crossing day, with its flag over the plot. For a budget read as what's left, use an Limit Meter; for values over time with axes and tooltips, a Chart.

import { ForecastBand } from '@youj/react'

<ForecastBand
  // The running total at the end of each elapsed day; the last one is today.
  actual={[412, 880, 1335 /* … */]}
  // The forecast running total for each remaining day, with its likely range.
  forecast={[{ value: 8500, low: 8370, high: 8710 } /* … */]}
  budget={12000}
  start="2026-09-01"
  format={{ style: 'currency', currency: 'USD' }}
/>

The period runs from start for as many days as actual and forecast hold between them. Its days are named in the locale ("Sep 28"). Without start, the crossing is named from today ("in 9 days") and the axis numbers the days. The scale tops out at a round number above the budget and the forecast's high. Pass max to hold it still when the data changes, so the axis stays put while the paths morph. For a unit Intl has none for (tickets, kWh), pass formatValue instead of format: a function that writes every amount and the axis labels.

Reference

Propsactual, forecast, budget… (11)

Props

ForecastBand props
Prop	Type	Default
`actual`Required	`readonly number[]` The running total at the end of each elapsed day, the last one being today.	–
`forecast`Required	`readonly ForecastPoint[]` The forecast running total for each remaining day of the period.	–
`budget`Required	`number`	–
`start`	`Date \| string` The period's first day, to name dates ("Sep 28"). Without it the crossing is named relative to today ("in 9 days") and days are numbered.	–
`max`	`number` The top of the scale. Default: a round number above the budget and the forecast's high; pass one to keep the scale still across data.	–
`format`	`Intl.NumberFormatOptions` Intl.NumberFormat options for the amounts, e.g. `{ style: 'currency', currency: 'USD' }`.	–
`formatValue`	`(value: number) => string` Writes every amount (and the scale) with your own function, for units Intl has none for ("1,240 kWh"). Replaces `format`.	–
`locale`	`string` Default: the YoujProvider locale.	–
`label`	`string` Names the chart for assistive tech. Default: the labels' "Spend forecast".	–
`tone`	`ForecastTone` `'accent''neutral''chart-1''chart-2''chart-3''chart-4''chart-5'` The forecast's color: its line, range and hatch. default 'chart-5'	`'chart-5'`
`legend`	`boolean` Show the legend over the plot. default true	`true`
`scenario`	`ForecastScenario` A second path from today: what the total does if something changes.	–
Other props pass through: extends `ComponentProps<'div'>`.

StylingParts and data attributes

MotionReveal: actual, reveal: forecast, crossing… · reduced motion

Motion

Motion tokens
Moment	Tokens	Value
Reveal: actualwhen a third of the chart scrolls into view, the spend line and its wash draw in from the start to today (a clip, so nothing stretches)	`duration.deliberateease.emphasized` 560ms · cubic-bezier(0.6, 0, 0.1, 1)	560mscubic-bezier(0.6, 0, 0.1, 1)
Reveal: forecastthe forecast, its range and the hatch wipe on from today to the period’s end, starting as the actual line lands	`duration.slowease.enter` 340ms · cubic-bezier(0.16, 1, 0.3, 1)	340mscubic-bezier(0.16, 1, 0.3, 1)
Crossingthe marker arrives as the wipe reaches it, and its ring pulses once; the flag fades in over it	`spring.settle` 0.45s, bounce 0.3	0.45s, bounce 0.3
New dataevery path morphs to the new values (keep the point counts stable), and the budget line and the marker glide; the ring pulses once more only if the crossing day moves	`spring.smooth` 0.36s, bounce 0	0.36s, bounce 0
No crossingthe marker and its flag leave	`duration.fastease.exit` 140ms · cubic-bezier(0.4, 0, 1, 1)	140mscubic-bezier(0.4, 0, 1, 1)

Reduced motion

Drawn in place: no draw or wipe, the marker's ring static, new data landing at once.

Reduced motion

Everything is drawn in place. There's no draw, no wipe and no pulse, and new data lands at once.

AccessibilityLabels and assistive technology