One chart API. Native everywhere.

yarn add @hzblj/zyplot

npx expo prebuild
npx expo run:ios
npx expo run:android

import { Chart } from '@hzblj/zyplot'

export function Revenue() {
  return (
    <Chart.Line
      categories={['Jan', 'Feb', 'Mar']}
      format={{ prefix: '$' }}
      series={[{ id: 'revenue', label: 'Revenue', values: [42, 56, 51] }]}
    />
  )
}

forecast.ios.tsx      imports @hzblj/zyplot/ios
forecast.android.tsx  imports @hzblj/zyplot/android
forecast.tsx          optional web or fallback version

// forecast.ios.tsx
import { Chart } from '@hzblj/zyplot/ios'

export const Forecast = ({ bands }: ForecastProps) => (
  <Chart.Range data={bands} height={300} />
)

// forecast.android.tsx
import { Chart } from '@hzblj/zyplot/android'

export const Forecast = ({ bands }: ForecastProps) => (
  <Chart.Lollipop data={bands.map(toPoint)} height={300} />
)

type ChartGlow = {
  /** Defaults to the mark’s own colour. */
  color?: string
  opacity?: number
  radius?: number
}

/** A hard disc behind a point. Unlike a glow it has an edge. */
type ChartHalo = {
  color?: string
  opacity?: number
  size?: number
}

type ChartPulse = {
  /** Defaults to the glow's colour, then to the point's own. */
  color?: string
  /** One bloom, in ms. Default 450. */
  duration?: number
  /** The rest between blooms, in ms. Default 1550. */
  interval?: number
  /** How opaque the ring starts, before fading out over the bloom. Default 0.9. */
  opacity?: number
  /** How far it blooms, as a multiple of the point's resting ring. Default 2.2. */
  scale?: number
}

type ChartRevealAnimation = {
  /** "draw" | "fade" | "none" */
  style?: ChartRevealStyle
  duration?: number
  /** "ease-in" | "ease-in-out" | "ease-out" | "linear". Defaults to "linear" for a trace. */
  easing?: ChartRevealEasing
  /** A brief brightening as the trace lands. "draw" only. */
  flashColor?: string
  flashDuration?: number
  /** The curve the flash decays along once it has held. Defaults to "ease-out". */
  flashEasing?: ChartRevealEasing
  /** How far the glow blooms at the peak, as a multiple of its resting radius. */
  flashGlow?: number
  /** How long the flash holds at full strength before decaying. */
  flashHold?: number
  flashOpacity?: number
  /** How dim the stroke starts while being traced, as a fraction of its final opacity. */
  startOpacity?: number
  /** Draws the whole path in this colour under the trace, so the shape reads from frame one. */
  trackColor?: string
  trackOpacity?: number
}

/** How marks move when the data changes under a mounted chart. */
type ChartTransition = 'crossfade' | 'morph'

type ChartInteractionPhase = 'began' | 'changed' | 'ended' | 'layout'

type ChartInteractionEvent = {
  /** Position of the selected mark in the chart’s own data order. */
  index?: number
  phase?: ChartInteractionPhase
  /** Where the plot and its annotations sit, on the "layout" phase. */
  geometry?: ChartGeometry
  // … plus category, value, seriesId and the pointer position
}

type ChartGeometry = {
  annotations: readonly { id: string; x: number; y: number }[]
  plot: { height: number; width: number; x: number; y: number }
}

/** How the mark under the finger is picked out. */
type ChartSelectionMarker = {
  /** "point" | "segment" */
  style?: ChartMarkerStyle
  color?: string
  glow?: ChartGlow
  /** A dot’s diameter. "point" only. */
  size?: number
  /** How many data steps either side of the touch a segment covers. "segment" only. */
  span?: number
}

type ChartCrosshairStyle = {
  color?: string
  dash?: number[]
  width?: number
}

type ChartCandlestickLabels = {
  open: string
  high: string
  low: string
  close: string
  change: string
}

// price.ios.tsx
import { Chart } from '@hzblj/zyplot/ios'

export function Price() {
  return (
    <Chart.Candlestick
      data={candles}
      format={{ prefix: '$' }}
      onInteraction={(event) => console.log(event.category, event.value)}
      showVolume
    />
  )
}

// spend.android.tsx
import { Chart } from '@hzblj/zyplot/android'

export function Spend() {
  return (
    <Chart.Waterfall
      data={movements}
      format={{ prefix: '$', decimals: 0 }}
      interaction={{ haptics: true, tooltip: true }}
    />
  )
}

<Chart.Provider
  theme={{
    colors: {
      categorical: ['#7c3aed', '#0284c7', '#ea580c'],
      grid: '#e5e7eb',
    },
    typography: {
      fontFamily: 'Geist, sans-serif',
    },
  }}
>
  <Dashboard />
</Chart.Provider>

type ChartProviderTheme = {
  colors?: {
    /** Slots 1…7, in order. A series takes one by index or by its own slot. */
    categorical?: readonly string[]
    /** Low → high, five steps. Heatmap, treemap, sunburst. */
    sequential?: readonly string[]
    /** A signed scale in full. The flat negative/positive below are its shorthand. */
    diverging?: {
      negative?: string
      negativeSoft?: string
      neutral?: string
      positive?: string
      positiveSoft?: string
    }
    /** The de-emphasis grey — every series that is context rather than subject. */
    muted?: string
    axis?: string
    grid?: string
    /** Axis and data labels. */
    label?: string
    negative?: string
    positive?: string
    /** Tooltip fill. */
    surface?: string
    /** Tooltip hairline. */
    border?: string
    /** The unfilled part of a gauge or a meter. */
    track?: string
  }
  typography?: {
    /** A resolved family name. A canvas cannot read var(--font-sans). */
    fontFamily?: string
  }
}

import type { ChartTheme } from '@hzblj/zyplot'

type ChartTheme = {
  colors?: ChartThemeColors
  typography?: ChartTypography
}

type ChartThemeColors = {
  axis?: string
  /** Series colours, in the order series take them. */
  categorical?: readonly string[]
  grid?: string
  label?: string
  /** The negative half of a signed scale: a losing bar, a falling candle. */
  negative?: string
  positive?: string
  /** Tooltip fill. */
  surface?: string
  /** The unfilled part of a gauge or a meter. */
  track?: string
}

/** The one colour only a native chart paints for itself. */
type NativeChartTheme = {
  colors?: ChartThemeColors & { background?: string }
  typography?: ChartTypography
}

<Chart.Provider surface={{ background: '#fff', cornerRadius: 16, padding: 12 }}>
  <Chart.Line categories={categories} series={series} />
  <Chart.Bar surface={{ cornerRadius: 24 }} categories={categories} series={series} />
</Chart.Provider>

:root {
  /* Categorical: slots 1…7, in the order series take them. */
  --zyplot-color-categorical-1: #4400fc;
  --zyplot-color-categorical-2: #0092de;
  --zyplot-color-categorical-3: #ff5700;
  --zyplot-color-categorical-4: #9c74ff;
  --zyplot-color-categorical-5: #00a546;
  --zyplot-color-categorical-6: #006fac;
  --zyplot-color-categorical-7: #ff133c;

  /* Sequential: low → high. Heatmap, treemap, sunburst. */
  --zyplot-color-sequential-1: #b89bff;
  --zyplot-color-sequential-2: #9c74ff;
  --zyplot-color-sequential-3: #7135ff;
  --zyplot-color-sequential-4: #4400fc;
  --zyplot-color-sequential-5: #2f00ae;

  /* Diverging: signed scales. */
  --zyplot-color-diverging-negative: #d23100;
  --zyplot-color-diverging-negative-soft: #ff7d4f;
  --zyplot-color-diverging-neutral: #d9d9d9;
  --zyplot-color-diverging-positive-soft: #59c4fd;
  --zyplot-color-diverging-positive: #006fac;

  /* Chrome. */
  --zyplot-color-axis: #a6a6a6;
  --zyplot-color-grid: #f5f5f5;
  --zyplot-color-label: #666666;
  --zyplot-color-muted: #808080;
  --zyplot-color-surface: #fcfcfc;
  --zyplot-color-border: #f5f5f5;
  --zyplot-color-track: #ebebeb;

  --zyplot-font-family: inherit;
}

/* Only the keys you actually change need restating per mode. */
[data-theme='dark'] {
  --zyplot-color-categorical-1: #7135ff;
  --zyplot-color-grid: #212121;
}

type ChartSeries = {
  /** Stable identity: the React key, and how hover correlates across charts. */
  id: string
  /** Already-translated display name, used by the legend and the tooltip. */
  label: string
  /** One value per category. null is a genuine gap, drawn as one, never as zero. */
  values: (number | null)[]
  /** Palette slot, 1-based. Pin it when the caller can hide series. */
  slot?: number
  /** Overrides the active palette for this series. */
  color?: string
}

const series: ChartSeries[] = [
  {
    id: 'revenue',
    label: 'Revenue',
    values: [42, 56, null, 72],
    slot: 1,
    color: '#16a34a',
  },
]

type ChartDatum = {
  id: string
  label: string
  value: number
  slot?: number
  color?: string
}

type ChartAxes = {
  x?: boolean
  y?: boolean
}

type ChartNumberFormat = {
  /** Fraction digits. Defaults to 0. */
  decimals?: number
  /** BCP 47 tag for grouping and decimal separators. Defaults to the runtime locale. */
  locale?: string
  /** Rendered before the number — a currency symbol, typically. */
  prefix?: string
  /** Rendered after the number — a unit or a percent sign. */
  suffix?: string
}

type ChartLegendItem = {
  id: string
  label: string
  color: string
}

/** Chart.Radar — one axis per row. Axes are scaled independently. */
type ChartRadarAxis = {
  label: string
  max: number
}

/** Chart.Heatmap — addressed by axis index; null renders empty, not as the ramp's low end. */
type ChartHeatmapCell = {
  columnIndex: number
  rowIndex: number
  value: number | null
}

/** Chart.Dumbbell — a before → after pair per row. */
type ChartDumbbellRow = {
  id: string
  label: string
  before: number
  after: number
}

/** Chart.Boxplot — the five-number summary, plus outliers you have already picked. */
type ChartBoxplotGroup = {
  id: string
  label: string
  min: number
  q1: number
  median: number
  q3: number
  max: number
  outliers?: number[]
}

/** Required, because "Q1" is not a word every reader of your product knows. */
type BoxplotLabels = {
  min: string
  q1: string
  median: string
  q3: string
  max: string
}

/** Chart.Sankey — nodes, and the weighted edges that address them by id. */
type ChartFlowNode = {
  id: string
  label: string
  slot?: number
  color?: string
}

type ChartFlowLink = {
  source: string
  target: string
  value: number
}

/** Chart.Treemap and Chart.Sunburst — leaves carry a value, parents sum their children. */
type ChartHierarchyNode = {
  id: string
  label: string
  value?: number
  children?: ChartHierarchyNode[]
  slot?: number
  color?: string
}

/** Chart.Scatter — an unordered two-measure space. size turns points into bubbles. */
type ChartScatterSeries = {
  id: string
  label: string
  points: Array<{
    x: number
    y: number
    size?: number
    label?: string
  }>
  slot?: number
  color?: string
}

/** Chart.TimeSeries — parallel arrays, because that is what uPlot consumes. */
type ChartTimePoints = {
  /** Unix seconds, strictly ascending. */
  timestamps: number[]
  /** One entry per series, each as long as timestamps. */
  values: (number | null)[][]
}

type ChartCandlestickDatum = {
  id: string
  category: string
  open: number
  high: number
  low: number
  close: number
  volume?: number
  /** Unix seconds. */
  timestamp?: number
}

type ChartCandlestickStyle = {
  upColor?: string
  downColor?: string
  neutralColor?: string
  /** Draws rising candles as outlines — the convention on most trading desks. */
  hollowUp?: boolean
  /** Corner radius on the candle body. Rounds the wick's caps with it. */
  candleRadius?: number
  /** Body width as a share of the slot a candle sits in. */
  candleWidth?: number
  wickWidth?: number
  volumeUpColor?: string
  volumeDownColor?: string
  /** Share of the plot height the volume histogram takes. */
  volumeHeightRatio?: number
}

type ChartAxisOptions = {
  visible?: boolean
  label?: string
  /** "auto" | "category" | "linear" | "log" | "time" */
  scale?: ChartAxisScale
  domain?: ChartAxisDomain
  format?: ChartNumberFormat
  grid?: boolean
  gridDash?: number[]
  labelRotation?: number
  /** Which side the axis is drawn on: "start" | "end". */
  position?: ChartAxisPosition
  reversed?: boolean
  /** A hint, not a guarantee — the engine still picks readable ticks. */
  tickCount?: number
  /** Exact ticks, when the reader is looking for specific ones. */
  tickValues?: (number | string)[]
}

type ChartAxisDomain = {
  /** Pins the extent. Omit either end to keep it computed from the data. */
  min?: number
  max?: number
  /**
   * Headroom kept beyond the data, as a fraction of its extent — 0.08 leaves 8%
   * clear at each end. Applies only to an end that is computed, so it combines
   * with a single pinned one.
   */
  padding?: number
}

type ChartAnnotation =
  | ChartLineAnnotation
  | ChartRangeAnnotation
  | ChartPointAnnotation
  | ChartTextAnnotation

/** A target, a threshold, a launch date. */
type ChartLineAnnotation = {
  type: 'line'
  id: string
  axis: 'x' | 'y'
  value: number | string
  label?: string
  color?: string
  /** Dash and gap lengths. Omit for a solid rule. */
  dash?: number[]
  /** Rule thickness. Default 1. */
  width?: number
}

/** A shaded span — a quarter, an incident window, a tolerance band. */
type ChartRangeAnnotation = {
  type: 'range'
  id: string
  axis: 'x' | 'y'
  start: number | string
  end: number | string
  label?: string
  color?: string
  opacity?: number
}

type ChartPointAnnotation = {
  type: 'point'
  id: string
  x: number | string
  y: number
  label?: string
  color?: string
  symbol?: ChartSymbol
}

type ChartTextAnnotation = {
  type: 'text'
  id: string
  text: string
  x?: number | string
  y?: number
  color?: string
}

type ChartInteraction = {
  /** "axis" | "nearest" | "series" | "none" */
  hover?: ChartHoverMode
  /** "both" | "x" | "y" | "none" */
  crosshair?: ChartCrosshairMode
  tooltip?: boolean
  /** "single" | "multiple" | "none" */
  selection?: ChartSelectionMode
  pan?: boolean
  zoom?: boolean
  /** How far a hovered mark grows. */
  highlightScale?: number
  /** How far the rest fades while one mark is hovered. */
  dimOpacity?: number
  /** A colour the read mark is lifted towards, so it reads as lit rather than as undimmed. */
  highlightColor?: string
  /** How far towards it, 0–1. Below 1 the mark's own colour still reads. Default 1. */
  highlightBlend?: number
  /** Native only — the web has no honest equivalent. */
  haptics?: boolean
}

type ChartInteractionEvent = {
  seriesId?: string
  category?: string
  value?: number
  x?: number
  y?: number
  /** Unix seconds, on the time-based forms. */
  timestamp?: number
  /** Pointer position in the chart's own coordinate space. */
  nativeX?: number
  nativeY?: number
  /** Position of the read mark in the chart's own data order. */
  index?: number
  /** "began" | "changed" | "ended" | "layout" */
  phase?: ChartInteractionPhase
  /** Where the plot and its annotations sit, on the "layout" phase. */
  geometry?: ChartGeometry
}

type ChartPlotStyle = {
  backgroundColor?: string
  borderColor?: string
  borderWidth?: number
  borderRadius?: number
  /** Clips marks to the plot area — the honest choice when a domain is pinned. */
  clip?: boolean
  padding?: number | { top?: number; right?: number; bottom?: number; left?: number }
}

type ChartSeriesStyle = {
  color?: string
  strokeWidth?: number
  strokeDash?: number[]
  fillOpacity?: number
  opacity?: number
  /** "circle" | "diamond" | "square" | "triangle" | "none" */
  symbol?: ChartSymbol
  symbolSize?: number
}

type ChartAnimation = {
  enabled?: boolean
  /** The entrance. Turn it off for a chart that re-renders on every keystroke. */
  initial?: boolean
  /** The transition when data changes under a mounted chart. */
  updates?: boolean
  duration?: number
  /** How long the entrance waits before it starts. A beat here keeps a trace from being
   * drawn under a navigation transition, where its first part is never seen. */
  delay?: number
  /** "linear" | "ease-in" | "ease-out" | "ease-in-out" | "spring" */
  easing?: ChartAnimationEasing
}

import {
  // Builders with variants, one function per variant.
  annotation,
  axis,
  marker,
  reveal,
  // A series and its styling, declared together.
  series,
  seriesProps,
  // Typed passthroughs for the groups with nothing to get wrong.
  animation,
  format,
  glow,
  halo,
  interaction,
  plot,
  seriesStyle,
  surface,
  theme,
} from '@hzblj/zyplot'

const lines = useMemo(
  () =>
    seriesProps([
      series({
        color: '#ff3b4a',
        id: 'price',
        label: 'Price',
        style: { glow: glow({ opacity: 0.16, radius: 7 }), strokeWidth: 2.3 },
        values: range.values,
      }),
    ]),
  [range]
)

<Chart.Line {...lines} categories={range.categories} />

const baseline = (value: number, label: string) =>
  annotation.line({
    axis: 'y',
    // Omit dash for a solid rule; width is in points on both platforms.
    dash: [1, 4],
    id: 'baseline',
    label,
    // A dark chip behind the digits, and the side that keeps them inside the plot.
    labelBackground: '#000000',
    labelPosition: 'auto',
    // Fade the rule out entirely while a price is being read.
    scrubOpacity: 0,
    value,
    width: 1.5,
  })

const marketOpen = (category: string) =>
  annotation.line({ axis: 'x', badge: '↑', dash: [2, 4], id: 'open', size: 18, value: category })

<Chart.Line annotations={[baseline(range.baseline, 'Prev close'), marketOpen('09:30')]} … />

const priceAxis = (domain: { max: number; min: number }) =>
  axis.overlay({
    domain,
    format: { decimals: 2 },
    grid: false,
    labelInset: 22,
    labelSize: 13,
    ticks: false,
    // Only the two prices a reader is actually looking for.
    tickValues: [domain.min, domain.max],
  })

<Chart.Line xAxis={axis.start({ grid: false })} yAxis={priceAxis(domain)} … />

const arrival = animation({
  reveal: reveal.draw({
    duration: 420,
    // A brief brightening as the trace lands.
    flashColor: '#ffe3e8',
    flashDuration: 480,
    // Hold the glow a beat, then let it leave in one piece.
    flashEasing: 'ease-in-out',
    flashHold: 220,
    // Draw the whole path faintly first, so the shape reads from frame one.
    trackColor: '#8a8a8a',
    trackOpacity: 0.4,
  }),
  updates: false,
})

<Chart.Line animation={arrival} … />

const scrubbing = interaction({
  crosshair: 'x',
  crosshairStyle: { color: '#ffffff', width: 1 },
  // Dim the rest of the line so the lit segment reads as the reading.
  dimOpacity: 0.38,
  haptics: true,
  hover: 'nearest',
  marker: marker.segment({
    color: '#ffffff',
    glow: glow({ color: '#ff3b4a', opacity: 0.32, radius: 42 }),
    span: 2,
  }),
})

<Chart.Line interaction={{ ...scrubbing, tooltip: false }} … />

// chart-style.ts — declared once, imported by both the line and the candlestick chart.
export const chartTheme = theme({ colors: { label: '#8a8a8a' } })
export const priceFormat = format({ decimals: 2, locale: 'en-US' })
export const card = surface({ background: '#0b0b0b', cornerRadius: 16, padding: 12 })
export const priceLine = seriesStyle({ glow: glow({ opacity: 0.16, radius: 7 }), strokeWidth: 2.3 })

'use client'

import { Chart, marker, useChartScrub } from '@hzblj/zyplot'

export const Price = ({ prices, categories }: PriceProps) => {
  const { onInteraction, selection } = useChartScrub()
  const shown = selection ? prices[selection.index] : prices.at(-1)

  return (
    <>
      <Text>{shown}</Text>
      <Text>{selection ? categories[selection.index] : 'Today'}</Text>
      <Chart.Line
        categories={categories}
        interaction={{ crosshair: 'x', haptics: true, marker: marker.segment(), tooltip: false }}
        onInteraction={onInteraction}
        series={[{ id: 'price', label: 'Price', values: prices }]}
      />
    </>
  )
}

type ChartScrubSelection = {
  /** Position of the mark in the chart’s own data order. */
  index: number
  category?: string
  /** Where the finger is, in the chart view’s own coordinate space. */
  nativeX?: number
  nativeY?: number
  value?: number
}

type ChartGeometry = {
  annotations: readonly { id: string; x: number; y: number }[]
  plot: { height: number; width: number; x: number; y: number }
}

import { annotation, Chart, useLastReading } from '@hzblj/zyplot'

export const Price = ({ prices, categories }: PriceProps) => {
  const live = useLastReading(categories, prices)

  return (
    <Chart.Line
      annotations={live ? [annotation.point({ id: 'live', x: live.category, y: live.value })] : []}
      annotationViews={{ live: <LiveBadge value={live?.value} /> }}
      categories={categories}
      series={[{ id: 'price', label: 'Price', values: prices }]}
    />
  )
}

'use client'

import { annotation, Chart, useChartScrub } from '@hzblj/zyplot'

export const Price = ({ prices, categories }: PriceProps) => {
  const { geometry, onInteraction, selection } = useChartScrub()
  const dividend = geometry?.annotations.find((mark) => mark.id === 'dividend')

  return (
    <View>
      <Chart.Line
        annotations={[
          // No badge: the rule is the chart's, the head is yours.
          annotation.line({ axis: 'x', dash: [2, 4], id: 'dividend', value: '12 Jul' }),
        ]}
        categories={categories}
        interaction={{ crosshair: 'x', haptics: true, tooltip: false }}
        onInteraction={onInteraction}
        series={[{ id: 'price', label: 'Price', values: prices }]}
      />

      {dividend ? (
        <Pressable
          onPress={openDividend}
          style={[styles.badge, { left: dividend.x - 9, top: dividend.y - 9 }]}
        >
          <Text>D</Text>
        </Pressable>
      ) : null}

      {selection ? (
        <Card left={selection.nativeX} rows={events[selection.index]} />
      ) : null}
    </View>
  )
}

const live = useLastReading(range.categories, range.values)

<Chart.Line
  annotations={
    live
      ? [
          annotation.point({
            color: '#ffffff',
            glow: glow({ color: '#ff3b4a', opacity: 0.25, radius: 3 }),
            halo: halo({ color: '#ff3b4a', size: 11 }),
            id: 'live',
            pulse: true,
            size: 4.7,
            x: live.category,
            y: live.value,
          }),
        ]
      : []
  }
  categories={range.categories}
  series={[{ id: 'price', label: 'Price', values: range.values }]}
/>

type ChartReading = {
  category: string
  index: number
  value: number
}

<Chart.Line
  categories={categories}
  height={320}
  isLoading={revenue.isPending}
  series={series}
/>

<Suspense fallback={<Chart.Line.Skeleton height={320} legendCount={2} />}>
  <Revenue />
</Suspense>

function RevenueSkeleton({ height = 320 }) {
  return (
    <div
      aria-label="Loading revenue chart"
      aria-busy="true"
      role="status"
      style={{ height }}
    >
      <div className="skeleton-title" />
      <div className="skeleton-plot" />
    </div>
  )
}

<Chart.Line
  isLoading
  skeleton={<RevenueSkeleton height={320} />}
  height={320}
  axis={{ x: false, y: true }}
  categories={categories}
  series={series}
/>

<Chart.Frame
  title="Revenue"
  description="Monthly recurring revenue"
  caption="Source: billing ledger"
>
  <Chart.Line categories={categories} series={series} />
</Chart.Frame>