react-native-livechart 3.5.1 → 3.7.0

package/src/hooks/crosshairShared.ts

@@ -190,6 +190,18 @@ export function computeTooltipLayout(
    *  every frame, and `measureText` shapes text each call (a real cost,
    *  especially in the simulator). Falls back to `measureText` when 0. */
   monoCharWidth = 0,
+  /** Where the pill sits relative to the scrub line. `"side"` offsets it right
+   *  (flipping left near the edge); `"top"`/`"bottom"` center it over the line,
+   *  clamped into the plot and pinned to the plot's top/bottom. */
+  placement: "side" | "top" | "bottom" = "side",
+  /** Render the value row. */
+  showValue = true,
+  /** Render the time row. */
+  showTime = true,
+  /** Canvas height in px — needed to pin `"bottom"` placement. */
+  canvasHeight = 0,
+  /** Gap in px between the pill and the plot edge it's pinned to. */
+  margin = TOOLTIP_TOP_MARGIN,
 ): TooltipLayout {
   "worklet";
   if (!scrubActive || scrubValue === null) return HIDDEN_TOOLTIP;
@@ -199,9 +211,19 @@ export function computeTooltipLayout(
   const valueStr = formatValue(v);
   const timeStr = formatTime(t);
 
+  // Content toggles: pick which rows render. Guard both-off → keep the time row.
+  let sv = showValue;
+  let st = showTime;
+  let rowCount = (sv ? 1 : 0) + (st ? 1 : 0);
+  if (rowCount === 0) {
+    st = true;
+    rowCount = 1;
+  }
+
   const fm = font.getMetrics();
   const lineH = -fm.ascent + fm.descent;
-  const totalH = TOOLTIP_PAD_Y * 2 + lineH * 2 + TOOLTIP_LINE_GAP;
+  const totalH =
+    TOOLTIP_PAD_Y * 2 + lineH * rowCount + TOOLTIP_LINE_GAP * (rowCount - 1);
 
   const valueW =
     monoCharWidth > 0
@@ -211,19 +233,39 @@ export function computeTooltipLayout(
     monoCharWidth > 0
       ? timeStr.length * monoCharWidth
       : measureFontTextWidth(font, timeStr);
-  const contentW = Math.max(valueW, timeW);
+  // Only the visible rows contribute to the pill width.
+  const contentW = Math.max(sv ? valueW : 0, st ? timeW : 0);
   const pillW = contentW + TOOLTIP_PAD_X * 2;
 
   const rightEdge = canvasWidth - padding.right;
 
-  let pillX = scrubX + TOOLTIP_OFFSET_X;
-  if (pillX + pillW > rightEdge - TOOLTIP_EDGE_GAP) {
-    pillX = scrubX - pillW - TOOLTIP_OFFSET_X;
+  let pillX: number;
+  let pillY: number;
+  if (placement === "side") {
+    pillX = scrubX + TOOLTIP_OFFSET_X;
+    if (pillX + pillW > rightEdge - TOOLTIP_EDGE_GAP) {
+      pillX = scrubX - pillW - TOOLTIP_OFFSET_X;
+    }
+    pillY = padding.top + margin;
+  } else {
+    // Centered horizontally over the scrub line, clamped into the plot.
+    const leftBound = padding.left + TOOLTIP_EDGE_GAP;
+    const rightBound = rightEdge - TOOLTIP_EDGE_GAP - pillW;
+    pillX = Math.min(
+      Math.max(scrubX - pillW / 2, leftBound),
+      Math.max(leftBound, rightBound),
+    );
+    pillY =
+      placement === "top"
+        ? padding.top + margin
+        : canvasHeight - padding.bottom - margin - totalH;
   }
-  const pillY = padding.top + TOOLTIP_TOP_MARGIN;
 
-  const line1Y = pillY + TOOLTIP_PAD_Y - fm.ascent;
-  const line2Y = line1Y + lineH + TOOLTIP_LINE_GAP;
+  // line1Y = first rendered row's baseline; line2Y = second (when both shown).
+  // The overlay maps value→line1Y and time→(showValue ? line2Y : line1Y).
+  const firstBaseline = pillY + TOOLTIP_PAD_Y - fm.ascent;
+  const line1Y = firstBaseline;
+  const line2Y = firstBaseline + lineH + TOOLTIP_LINE_GAP;
 
   const valueTextX = pillX + TOOLTIP_PAD_X + (contentW - valueW) / 2;
   const timeTextX = pillX + TOOLTIP_PAD_X + (contentW - timeW) / 2;
@@ -618,6 +660,11 @@ export function deriveCrosshairTooltipSingle(
   formatTime: (t: number) => string,
   font: SkFont,
   monoCharWidth = 0,
+  placement: "side" | "top" | "bottom" = "side",
+  showValue = true,
+  showTime = true,
+  canvasHeight = 0,
+  margin = TOOLTIP_TOP_MARGIN,
 ): TooltipLayout {
   "worklet";
   if (!scrubActive || scrubTime < 0) return HIDDEN_TOOLTIP;
@@ -632,5 +679,10 @@ export function deriveCrosshairTooltipSingle(
     formatTime,
     font,
     monoCharWidth,
+    placement,
+    showValue,
+    showTime,
+    canvasHeight,
+    margin,
   );
 }

package/src/hooks/useCrosshair.ts

@@ -129,6 +129,14 @@ export function useCrosshair(
    * Omitted when nothing coexists.
    */
   deferTapHit?: (x: number, y: number) => boolean,
+  /** Where the tooltip pill sits relative to the scrub line. Default `"side"`. */
+  tooltipPlacement: "side" | "top" | "bottom" = "side",
+  /** Render the value row in the default tooltip. Default `true`. */
+  tooltipShowValue = true,
+  /** Render the time row in the default tooltip. Default `true`. */
+  tooltipShowTime = true,
+  /** Gap (px) between the tooltip and the plot edge it's pinned to. Default `8`. */
+  tooltipMargin = 8,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
@@ -247,6 +255,11 @@ export function useCrosshair(
       formatTime,
       font,
       monoCharWidth,
+      tooltipPlacement,
+      tooltipShowValue,
+      tooltipShowTime,
+      engine.canvasHeight.get(),
+      tooltipMargin,
     );
   });
 

package/src/index.ts

@@ -79,6 +79,7 @@ export type {
   ThemeMode,
   ThresholdConfig,
   ThresholdLineConfig,
+  TooltipRenderProps,
   TradeEvent,
   ValueLineConfig,
   XAxisConfig,

package/src/types.ts

@@ -378,6 +378,27 @@ export interface ScrubConfig {
   tooltipColor?: string;
   /** Tooltip pill border color. Omit to use theme `tooltipBorder`. */
   tooltipBorderColor?: string;
+  /** Tooltip pill corner radius in px. Default `5`. */
+  tooltipBorderRadius?: number;
+  /**
+   * Where the tooltip pill sits relative to the vertical scrub line.
+   * `"side"` (default) offsets it to the right of the line and flips left near
+   * the right edge. `"top"` / `"bottom"` center it horizontally over the line,
+   * clamped into the plot and pinned to the plot's top or bottom. This also
+   * drives a custom {@link LiveChartProps.renderTooltip} so it gets the same
+   * placement for free.
+   */
+  tooltipPlacement?: "side" | "top" | "bottom";
+  /**
+   * Gap in px between the tooltip and the plot edge it's pinned to — the top for
+   * `"side"`/`"top"`, the bottom for `"bottom"`. Applies to the built-in pill and
+   * a custom {@link LiveChartProps.renderTooltip}. Default `8`.
+   */
+  tooltipMargin?: number;
+  /** Show the value row in the default tooltip body. Default `true`. */
+  tooltipShowValue?: boolean;
+  /** Show the time row in the default tooltip body. Default `true`. */
+  tooltipShowTime?: boolean;
   /**
    * Press-and-hold delay in milliseconds before scrubbing activates — think of
    * it as "press and hold to scrub." During the delay the pan is not captured,
@@ -473,6 +494,28 @@ export interface SelectionDotProps {
   size: number;
 }
 
+/**
+ * Context passed to a custom {@link LiveChartProps.renderTooltip}. The element
+ * you return is a React Native view that the chart floats over the canvas and
+ * positions on the UI thread (per `scrub.tooltipPlacement`) — so movement stays
+ * smooth without JS re-renders, unlike rebuilding the tooltip from the JS-thread
+ * `onScrub` callback. Bind the SharedValues here to animated text (e.g. an
+ * `Animated.createAnimatedComponent(TextInput)` driven by `useAnimatedProps`)
+ * for the value/date to update on the UI thread too.
+ */
+export interface TooltipRenderProps {
+  /** Interpolated value under the crosshair; `null` when none. */
+  value: SharedValue<number | null>;
+  /** Window time (unix seconds) under the crosshair. */
+  time: SharedValue<number>;
+  /** Value formatted with the chart's `formatValue` (computed UI-side). */
+  valueStr: SharedValue<string>;
+  /** Time formatted with the chart's `formatTime` (computed UI-side). */
+  timeStr: SharedValue<string>;
+  /** Whether scrubbing is currently active. */
+  active: SharedValue<boolean>;
+}
+
 /** Outer ring drawn around the built-in selection dot (the subtle halo). */
 export interface SelectionDotRingConfig {
   /** Ring color. Defaults to the dot color. */
@@ -1011,6 +1054,34 @@ export interface LiveChartCoreProps {
   onMarkerHover?: (event: MarkerHoverEvent | null) => void;
   /** Tap hit-test radius in px. Default `16` (≈ 44px touch target with the glyph). */
   markerHitRadius?: number;
+  /**
+   * Render a marker as a custom **React Native** element instead of a built-in
+   * Skia glyph — e.g. an `expo-blur` glass badge or any non-Skia view that the
+   * canvas can't draw. Return an element to float it, auto-centered, at the
+   * marker's live `(time, value)` position (tracked on the UI thread); return
+   * `null`/`undefined` to keep the built-in atlas glyph for that marker.
+   *
+   * The element is rendered as an RN view layered over the canvas, so it is
+   * crisp at native resolution. Use it sparingly (a handful of special markers):
+   * each custom marker is its own animated view + projection, whereas built-in
+   * glyphs batch into a single draw call. Custom-rendered markers skip the atlas
+   * glyph entirely (no double-draw).
+   */
+  renderMarker?: (marker: Marker) => ReactElement | null | undefined;
+  /**
+   * Render a fully custom scrub tooltip as a **React Native** element instead of
+   * the built-in pill — the same idea as `renderMarker`. The chart floats the
+   * returned element over the canvas and positions it on the UI thread per
+   * `scrub.tooltipPlacement` (so it stays smooth, unlike rebuilding the tooltip
+   * from the JS-thread `onScrub`). You own the chrome (border radius/color,
+   * background are plain RN styles) and content — bind the {@link
+   * TooltipRenderProps} SharedValues to animated text for the value/date.
+   *
+   * Return `null`/`undefined` to fall back to the built-in pill. Replaces the
+   * default pill entirely while active. Single-series **line mode only** —
+   * ignored in candle mode (the OHLC stack owns the tooltip there).
+   */
+  renderTooltip?: (ctx: TooltipRenderProps) => ReactElement | null | undefined;
   /**
    * Override individual resolved-palette keys on top of the palette derived from
    * `accentColor` + `theme`. Only the keys you set are replaced.