Site color

Choose your site’s color palette.

Saved on this device.

LineChart

LineChartOrdered trends

Make change easy to follow. Compare series, reveal individual observations, and choose linear or smooth curves with optional areas.

Charts & large data

Playground

Edit either series, rename it, or hide it to inspect the other line. Try crossing trends, gains and losses, a flat baseline or a single observation. Every chart control below is reactive, and Reset restores the full example. All data is illustrative.

LineChart in contextCOMPOSITION

Edit and rename series, toggle their visibility, and compare curves, areas, points, and labels.

<RegorApp id="line-chart-demo" src="./playground.ts"/>
import {
  defineBadgeComponents,
  defineButtonComponents,
  defineFlexComponents,
  defineFormComponents,
  defineFormInputField,
  defineFormSelectField,
  defineGridComponents,
  defineIconComponents,
  defineLineChartComponents,
  definePanelComponents,
  type FormSelectOption,
  type LineChartCurve,
  type LineChartSeries,
} from '@purestack/ts-components'
import { getThemePaletteVar, type SemanticTone } from '@purestack/ts-style'
import { lucide_chevron_down } from '@purestack/ts-svg-icons'
import {
  batch,
  type ComputedRef,
  computed,
  createApp,
  defineComponent,
  html,
  type Ref,
  ref,
  type SRef,
  sref,
} from 'regor'
import {
  type ChartAppearanceState,
  createChartAppearanceState,
  defineChartAppearanceControls,
} from '../../../../docs/dataGuide'

export type LineChartPreset =
  | 'growth'
  | 'crossing'
  | 'signed'
  | 'flat'
  | 'single'

export interface LineChartEditorPoint {
  id: string
  label: string
  value: Ref<number | string>
}

export interface LineChartEditorSeries {
  id: string
  label: Ref<string>
  enabled: Ref<boolean>
  tone: SemanticTone
  color: string
  points: LineChartEditorPoint[]
}

export interface LineChartPlayground extends ChartAppearanceState {
  editorSeries: SRef<LineChartEditorSeries[]>
  chartSeries: ComputedRef<LineChartSeries[]>
  summary: ComputedRef<string>
  replayDisabled: ComputedRef<boolean>
  preset: Ref<LineChartPreset>
  curve: Ref<LineChartCurve>
  suffix: Ref<string>
  minimum: Ref<number | string>
  maximum: Ref<number | string>
  height: Ref<number | string>
  areaVisible: Ref<boolean>
  pointsVisible: Ref<boolean>
  valuesVisible: Ref<boolean>
  labelsVisible: Ref<boolean>
  axisVisible: Ref<boolean>
  motionEnabled: Ref<boolean>
  presets: FormSelectOption[]
  curves: FormSelectOption[]
  units: FormSelectOption[]
  applyPreset: (event: Event) => void
  replay: () => void
  clear: () => void
  reset: () => void
}

const lineChartPlaygroundTemplate = html`<Flex direction="column">
  <Grid columns="1" columnsMd="3">
    <FormSelectField
      id="line-preset"
      label="Dataset"
      :model="preset"
      :options="presets"
      @change="applyPreset"/>
    <FormSelectField
      id="line-curve"
      label="Curve"
      :model="curve"
      :options="curves"/>
    <FormSelectField
      id="line-unit"
      label="Value suffix"
      :model="suffix"
      :options="units"/>
  </Grid>
  <ChartAppearanceControls
    prefix="line-chart-appearance"
    :tone="chartTone"
    :variant="chartVariant"
    :variantMode="chartVariantMode"
    :width="chartWidth"
    :showWidth="true"/>
  <Panel variant="surfaceAlt" bodyClass="p-3 min-w-0">
    <Flex justify="between" align="center" wrap="true">
      <p class="text-eyebrow m-0">LIVE PREVIEW · SERIES COMPARISON</p>
      <Btn
        variant="outline"
        size="sm"
        :disabled="replayDisabled"
        @click="replay"
        >Replay animation</Btn>
    </Flex>
    <Flex wrap="true" class="mt-3">
      <template r-for="entry in editorSeries">
        <Badge r-if="entry.enabled" :tone="entry.tone" variant="surface"
          >{{ entry.label }}</Badge>
      </template>
    </Flex>
    <div
      class="overflow-x-auto"
      tabindex="0"
      role="region"
      aria-label="Scrollable line chart preview"
    >
      <LineChart
        :tone="chartTone"
        :variant="chartVariant"
        :variantMode="chartVariantMode"
        :width="chartWidth"
        :series="chartSeries"
        title="Illustrative series comparison"
        description="Equally spaced observations. Exact values can be edited in each series below."
        :ariaLabel="summary"
        emptyLabel="No visible series"
        :curve="curve"
        :valueSuffix="suffix"
        :minValue="minimum"
        :maxValue="maximum"
        :height="height"
        :showArea="areaVisible"
        :showPoints="pointsVisible"
        :showValues="valuesVisible"
        :showLabels="labelsVisible"
        :showAxis="axisVisible"
        :animated="motionEnabled"
        style="min-width: 440px"/>
    </div>
    <FormStatus>{{ summary }}</FormStatus>
  </Panel>
  <Flex wrap="true">
    <FormCheck id="line-area" label="Area fill" :checked="areaVisible"/>
    <FormCheck
      id="line-points"
      label="Point markers"
      :checked="pointsVisible"/>
    <FormCheck id="line-values" label="Values" :checked="valuesVisible"/>
    <FormCheck
      id="line-labels"
      label="Category labels"
      :checked="labelsVisible"/>
    <FormCheck
      id="line-axis"
      label="Grid and zero line"
      :checked="axisVisible"/>
    <FormCheck
      id="line-motion"
      label="Entrance animation"
      :checked="motionEnabled"/>
  </Flex>
  <Grid columns="1" columnsMd="3">
    <FormInputField
      id="line-min"
      label="Minimum bound"
      type="number"
      placeholder="Automatic"
      :model="minimum"/>
    <FormInputField
      id="line-max"
      label="Maximum bound"
      type="number"
      placeholder="Automatic"
      :model="maximum"/>
    <FormInputField
      id="line-height"
      label="Chart height (px)"
      type="number"
      min="180"
      step="20"
      :model="height"/>
  </Grid>
  <p class="m-0 text-muted">
    Blank bounds use the data range. Bounds always expand to include zero and
    all visible points. Scroll the preview horizontally on narrow screens.
  </p>
  <Flex justify="between" align="center" wrap="true">
    <h3 class="m-0">Edit the series</h3>
    <Flex wrap="true">
      <Btn variant="outline" @click="clear">Empty data</Btn>
      <Btn tone="accent" variant="surface" @click="reset">Reset playground</Btn>
    </Flex>
  </Flex>
  <Panel
    r-for="entry in editorSeries"
    tone="neutral"
    variant="surface"
    bodyClass="p-3 min-w-0"
    :aria-label="entry.label"
  >
    <Flex direction="column">
      <Flex justify="between" align="center" wrap="true">
        <FormInputField
          :id="'line-name-' + entry.id"
          label="Series name"
          :model="entry.label"/>
        <FormCheck
          :id="'line-enabled-' + entry.id"
          label="Show series"
          :checked="entry.enabled"/>
      </Flex>
      <Grid columns="2" columnsSm="3" columnsLg="5">
        <FormInputField
          r-for="point in entry.points"
          :id="point.id"
          :label="point.label"
          type="number"
          step="1"
          :model="point.value"/>
      </Grid>
    </Flex>
  </Panel>
</Flex>`

const presetValues: Record<LineChartPreset, [number[], number[]]> = {
  growth: [
    [18, 26, 37, 48, 64],
    [10, 18, 25, 34, 43],
  ],
  crossing: [
    [20, 38, 28, 58, 48],
    [48, 26, 50, 32, 64],
  ],
  signed: [
    [-18, -8, 12, 28, 40],
    [-32, -18, -4, 12, 22],
  ],
  flat: [
    [24, 24, 24, 24, 24],
    [12, 12, 12, 12, 12],
  ],
  single: [[24], [12]],
}

function createLineChartSeries(
  preset: LineChartPreset,
): LineChartEditorSeries[] {
  const colors = [
    getThemePaletteVar('semanticTone.accent.button.hover.bgcolor'),
    getThemePaletteVar('semanticTone.feature.button.hover.bgcolor'),
  ]
  return presetValues[preset].map((values, index) => ({
    id: String(index),
    label: ref(index === 0 ? 'Current' : 'Baseline'),
    enabled: ref(true),
    tone: index === 0 ? 'accent' : 'feature',
    color: colors[index],
    points: values.map((value, pointIndex) => ({
      id: `line-value-${index}-${pointIndex}`,
      label: `R${pointIndex + 1}`,
      value: ref<number | string>(value),
    })),
  }))
}

function createLineChartPlayground(): LineChartPlayground {
  const appearance = createChartAppearanceState()
  const editorSeries = sref(createLineChartSeries('growth'))
  const preset = ref<LineChartPreset>('growth')
  const curve = ref<LineChartCurve>('smooth')
  const suffix = ref('%')
  const minimum = ref<number | string>('')
  const maximum = ref<number | string>('')
  const height = ref<number | string>(300)
  const areaVisible = ref(false)
  const pointsVisible = ref(true)
  const valuesVisible = ref(false)
  const labelsVisible = ref(true)
  const axisVisible = ref(true)
  const motionEnabled = ref(true)
  const chartSeries = computed<LineChartSeries[]>(() =>
    editorSeries()
      .filter((entry) => entry.enabled())
      .map((entry, index) => ({
        label: entry.label().trim() || `Series ${index + 1}`,
        color: entry.color,
        points: entry.points.map((point) => ({
          label: point.label,
          value: Number(point.value()),
        })),
      })),
  )
  return {
    ...appearance,
    editorSeries,
    chartSeries,
    summary: computed(() => {
      const visible = editorSeries().filter((entry) => entry.enabled())
      if (!visible.length)
        return 'No visible series. Enable a series, choose a dataset, or reset.'
      return visible
        .map((entry, index) => {
          const latest = entry.points.at(-1)
          return `${entry.label().trim() || `Series ${index + 1}`}: ${latest?.label} = ${Number(latest?.value())}${suffix()}`
        })
        .join(' · ')
    }),
    replayDisabled: computed(() => !motionEnabled() || !chartSeries().length),
    preset,
    curve,
    suffix,
    minimum,
    maximum,
    height,
    areaVisible,
    pointsVisible,
    valuesVisible,
    labelsVisible,
    axisVisible,
    motionEnabled,
    presets: [
      { label: 'Steady growth', value: 'growth' },
      { label: 'Crossing trends', value: 'crossing' },
      { label: 'Gains and losses', value: 'signed' },
      { label: 'Flat series', value: 'flat' },
      { label: 'Single observation', value: 'single' },
    ],
    curves: [
      { label: 'Smooth', value: 'smooth' },
      { label: 'Linear', value: 'linear' },
    ],
    units: [
      { label: 'Percent (%)', value: '%' },
      { label: 'Milliseconds (ms)', value: 'ms' },
      { label: 'No suffix', value: '' },
    ],
    applyPreset: (event) => {
      const next = (event.target as HTMLSelectElement).value as LineChartPreset
      editorSeries(createLineChartSeries(next))
    },
    replay: () => {
      for (const animation of document.querySelectorAll<SVGAnimationElement>(
        '#line-chart-demo .line-chart animate',
      )) {
        animation.beginElement()
      }
    },
    clear: () => editorSeries([]),
    reset: () =>
      batch(() => {
        appearance.resetAppearance()
        preset('growth')
        curve('smooth')
        suffix('%')
        minimum('')
        maximum('')
        height(300)
        areaVisible(false)
        pointsVisible(true)
        valuesVisible(false)
        labelsVisible(true)
        axisVisible(true)
        motionEnabled(true)
        editorSeries(createLineChartSeries('growth'))
      }),
  }
}

const lineChartPlayground = defineComponent<LineChartPlayground>(
  lineChartPlaygroundTemplate,
  {
    context: createLineChartPlayground,
  },
)
const icons: Record<string, string> = {
  'lucide:chevron-down': lucide_chevron_down,
}

createApp(
  {
    components: {
      ChartAppearanceControls: defineChartAppearanceControls(),
      LineChartPlayground: lineChartPlayground,
      ...defineBadgeComponents(),
      ...defineButtonComponents(),
      ...defineFlexComponents(),
      ...defineFormComponents(),
      ...defineFormInputField(),
      ...defineFormSelectField(),
      ...defineGridComponents(),
      ...defineIconComponents((name) => icons[name] ?? ''),
      ...defineLineChartComponents(),
      ...definePanelComponents(),
    },
  },
  { selector: 'app#line-chart-demo', template: html`<LineChartPlayground/>` },
)

Entrance animation starts enabled. Use Replay animation to run the SVG animations again without changing your data. Turn it off for immediate comparisons while editing. With overlapping series, hide value labels and use the named input fields to read exact values.

Compare aligned series

Give each series the same ordered categories and a visible legend. A fixed zero-to-100 scale keeps this comparison consistent. These are illustrative percentages.

Adoption across five releases

Current Previous
Adoption by release 100% 75% 50% 25% 0% Current Previous Current, R1: 18% Current, R2: 26% Current, R3: 37% Current, R4: 48% Current, R5: 64% Previous, R1: 10% Previous, R2: 18% Previous, R3: 25% Previous, R4: 34% Previous, R5: 43% R1R2R3R4R5
<Panel variant="surface" bodyClass="p-3">
  <h3 class="mt-0">Adoption across five releases</h3>
  <Flex wrap="true">
    <Badge tone="accent">Current</Badge>
    <Badge tone="feature">Previous</Badge>
  </Flex>
  <LineChart
    title="Adoption by release"
    ariaLabel="R1 to R5: Current 18, 26, 37, 48, 64 percent; Previous 10, 18, 25, 34, 43 percent"
    :series="[
      {label:'Current',points:[{label:'R1',value:18},{label:'R2',value:26},{label:'R3',value:37},{label:'R4',value:48},{label:'R5',value:64}]},
      {label:'Previous',points:[{label:'R1',value:10},{label:'R2',value:18},{label:'R3',value:25},{label:'R4',value:34},{label:'R5',value:43}]}
    ]"
    minValue="0"
    maxValue="100"
    valueSuffix="%"
    height="280"
    curve="linear"
  />
</Panel>

Fill an area across zero

Area fill closes each path against zero. Positive and negative regions keep their direction, while value labels show the actual observations. Multiple series would overlap; area fill is not stacking.

Change from the release baseline 40% 20% 0% -20% -40% Change Change, R1: -32% Change, R2: -12% Change, R3: 8% Change, R4: 24% Change, R5: 36% -32%-12%8%24%36% R1R2R3R4R5
<LineChart
  title="Change from the release baseline"
  ariaLabel="R1 minus 32 percent, R2 minus 12, R3 plus 8, R4 plus 24, R5 plus 36"
  :series="[{label:'Change',points:[{label:'R1',value:-32},{label:'R2',value:-12},{label:'R3',value:8},{label:'R4',value:24},{label:'R5',value:36}]}]"
  minValue="-40"
  maxValue="40"
  valueSuffix="%"
  height="280"
  :showArea="true"
  :showValues="true"
/>

A compact trend card

Use a nearby headline to explain a small trend. Remove the axis, category labels and markers to emphasize its shape; retain the exact observations in the accessible name.

ILLUSTRATIVE LATENCY

18 ms latest measurement

Six observations across a tuning session.

Latency trend Latency
<Panel tone="accent" variant="surface" bodyClass="p-3">
  <p class="text-eyebrow mt-0">ILLUSTRATIVE LATENCY</p>
  <h3>18 ms latest measurement</h3>
  <p>Six observations across a tuning session.</p>
  <LineChart
    title="Latency trend"
    ariaLabel="Latency measurements in milliseconds: 42, 36, 44, 29, 24, 18"
    :series="[{label:'Latency',points:[{value:42},{value:36},{value:44},{value:29},{value:24},{value:18}]}]"
    height="160"
    curve="linear"
    :showArea="true"
    :showAxis="false"
    :showLabels="false"
    :showPoints="false"
  />
</Panel>

Single-point and empty states

One observation needs a marker because there is no line segment yet. An empty series list displays your emptyLabel and removes the chart marks. Neither case needs placeholder data.

First measurement

First measurement 24% 18% 12% 6% 0% Current Current, R1: 24% 24% R1

Awaiting measurements

No measurements yet Waiting for the first run
<Grid columns="1" columnsMd="2">
  <Panel variant="surface" bodyClass="p-3">
    <h3 class="mt-0">First measurement</h3>
    <LineChart
      title="First measurement"
      ariaLabel="R1: 24 percent"
      :series="[{label:'Current',points:[{label:'R1',value:24}]}]"
      valueSuffix="%"
      height="220"
      :showPoints="true"
      :showValues="true"
    />
  </Panel>
  <Panel variant="surface" bodyClass="p-3">
    <h3 class="mt-0">Awaiting measurements</h3>
    <LineChart
      title="No measurements yet"
      emptyLabel="Waiting for the first run"
      :series="[]"
      height="220"
    />
  </Panel>
</Grid>

All ten semantic tones

Compare all ten tones together. These examples use tone-aware plot colors; custom data colors and the chart’s tone remain independent.

All ten semantic tonesCOMPOSITION

All samples use the same illustrative values. Switch the site theme to compare both palettes.

All eighteen visual variants

Every supported treatment is visible in accent, including none. The default chart variant is none; the live editor lets you combine any tone and treatment.

All eighteen visual variantsCOMPOSITION

All samples use the same illustrative values. Switch the site theme to compare both palettes.

Both variant modes

Stateless keeps the resting appearance. Stateful adds the treatment’s hover and active classes; hover the outlineFill examples to compare them. Charts default to stateless and retain their native plot hover feedback in either mode.

Both variant modesCOMPOSITION

All samples use the same illustrative values. Switch the site theme to compare both palettes.

Curves and display layers

Every layer is visible here without changing a toggle. Smooth interpolation is a visual treatment of equally spaced observations; it does not add observations to the data.

Compare curves and layersCOMPOSITION
Linear 48 36 24 12 0 Requests Requests, Mon: 18 Requests, Tue: 32 Requests, Wed: 25 Requests, Thu: 48 MonTueWedThu
Smooth 48 36 24 12 0 Requests Requests, Mon: 18 Requests, Tue: 32 Requests, Wed: 25 Requests, Thu: 48 MonTueWedThu
Area 48 36 24 12 0 Requests Requests, Mon: 18 Requests, Tue: 32 Requests, Wed: 25 Requests, Thu: 48 MonTueWedThu
Points and values 48 36 24 12 0 Requests Requests, Mon: 18 Requests, Tue: 32 Requests, Wed: 25 Requests, Thu: 48 18322548 MonTueWedThu
Only the line Requests
One observation 32 24 16 8 0 Requests Requests, Today: 32 32 Today
Empty No visible series

The live editor also supports multiple series, signed values, flat data, and one observation.

Feature map

Feature Where to try it
Reactive data and custom colors Edit and rename both series; hide one to compare the other. Each series carries its own color.
Tone, variant, and variantMode Use the three appearance controls; every option also appears in the galleries.
Accessible name and description The live chart binds ariaLabel to its exact-value summary; title and description are SVG metadata.
Empty label Choose Empty data; a dedicated empty sample is also visible above.
Units Change the value suffix in the live editor.
Size Change width and height; blank width preserves responsive sizing.
Entrance motion Toggle entrance animation and use Replay animation.
Domain Change minimum and maximum bounds. The range includes zero and every data value.

Behavior and accessibility

  • Category positions: points are equally spaced by index. Date-like labels are text; this is not a continuous time axis. Compared series need the same point count and category order.
  • Scale: automatic bounds include zero and all valid values. Explicit bounds can widen the range, but never crop measurements. Hiding a series can change an automatic scale.
  • Readable values: use markers, a visible legend and nearby data when exact comparisons matter. Narrow previews can scroll horizontally. Value labels from coincident series are not automatically separated.
  • Accessible context: provide a meaningful title and description or ariaLabel. Each point has an SVG title, while the playground also exposes the measurements through labelled native fields. Color is supported by named series and editable values.
  • Animation: paths fade in and markers grow on entrance. Area fills remain static. Replay uses each SVG animation's native beginElement method.

API reference

LineChart contract

Props below are the public template API. RefOrValue accepts a literal or a reactive ref; bind refs with a colon-prefixed attribute. Native attributes and events can be passed through the component root.

Data and accessible descriptions

series

RefOrValue<Array<RefOrValue<LineChartSeries>>>
Default
[]

An array of named series with optional CSS colors and ordered points. Keep category order and point counts aligned across compared series. The data contracts below show the supported ref shapes.

title

RefOrValue<string>
Default
not set

SVG title text. Add a visible heading outside the SVG when the chart needs one.

description

RefOrValue<string>
Default
not set

SVG description with context such as the metric, period and meaning of each series.

ariaLabel

RefOrValue<string>
Default
title, then Line chart

Accessible name on the SVG image.

emptyLabel

RefOrValue<string>
Default
No data

Visible fallback when no usable data remains.

valueSuffix

RefOrValue<string>
Default
not set

Unit appended to formatted values, such as ms or %.

Size and scale

width

RefOrValue<number | string>
Default
100%

CSS width. Numeric values become pixel lengths; strings can use CSS units.

height

RefOrValue<number | string>
Default
automatic

CSS height; omitted height preserves the SVG aspect ratio.

minValue

RefOrValue<number | string>
Default
automatic

Requested lower bound. The resolved range also includes zero and the smallest visible value. Leave it unset for automatic scaling; it never clips points.

maxValue

RefOrValue<number | string>
Default
automatic

Requested upper bound. The resolved range expands to include zero and the largest visible value. Use the same bounds on charts that should be compared.

Curves and visibility

curve

RefOrValue<LineChartCurve>
Default
smooth

smooth connects points with cubic curves; linear uses straight segments. Neither mode changes the measurements or adds intermediate observations.

animated

RefOrValue<boolean | string>
Default
true

Fades in paths and grows point markers when they mount. This does not interpolate between datasets or animate area fills. Disable it for rapid editing; the playground also shows how to replay the native SVG animations.

showArea

RefOrValue<boolean | string>
Default
false

Fills each series between its path and zero, including negative regions. Multiple areas overlap with transparency; they are not stacked.

showPoints

RefOrValue<boolean | string>
Default
true

Draws a marker with a native SVG title at each observation. Keep this enabled for a single-point series, whose path alone has no visible segment.

showValues

RefOrValue<boolean | string>
Default
false

Places values above positive points and below negative points. Labels from close or coincident series can overlap. Isolate a series or use the editable data fields for exact comparisons in a dense chart.

showLabels

RefOrValue<boolean | string>
Default
true

Shows labels from the first visible series, thinning them for long sequences and retaining the final label. Points are spaced by index, not by time or a numeric x coordinate.

showAxis

RefOrValue<boolean | string>
Default
true

Shows the axis grid and value labels.

Appearance

tone

RefOrValue<SemanticTone>
Default
inherited

Semantic intent: neutral, accent, secondary, info, success, warning, danger, feature, custom or ghost. The active skin supplies the colors.

variant

RefOrValue<ComponentVariant>
Default
none

Visual treatment. Accepts solid, surface, surfaceAlt, spotlight, glass, flat, flatAlt, flatSolid, outlineFill, outline, subtle, subtleBtn, link, sheen, underline, rail, bracket or none.

variantMode

RefOrValue<ComponentVariantMode>
Default
stateless

Use stateless for content surfaces; stateful enables the treatment’s hover, focus and active styles. It does not add interaction handlers.

Point and series contracts

import type { RefOrValue } from 'regor'

interface LineChartPoint {
  label?: RefOrValue<string>
  value?: RefOrValue<number | string>
}

interface LineChartSeries {
  label?: RefOrValue<string>
  color?: RefOrValue<string>
  points?: RefOrValue<Array<RefOrValue<LineChartPoint>>>
}

Missing names become Series 1 and Point 1. Non-finite values are removed; series with no valid points are removed too. Filtering a point closes the sequence, so missing observations do not create visible gaps. Normalize your data before comparing series.

Explicit colors stay attached to a series when others are hidden. Without a color, the palette is assigned by the visible series order. The playground uses theme variables so its legend and series colors stay consistent in both skins.

Composition

No slots. Register defineLineChartComponents. Series labels identify paths; provide an external legend or value list where readers need precise comparisons.