> ## Documentation Index
> Fetch the complete documentation index at: https://react-native-livechart.brandtnewlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chart gaps

> Represent no-trade, unavailable, and unknown line or candle intervals without fabricating market data.

Sparse timestamps are ambiguous: the market may have been open with no trades, trading may have
been unavailable, or the data feed may be incomplete. `lineGaps` and `candleGaps` attach that
meaning explicitly without inserting synthetic samples or OHLC records.

<Note>
  **Live example:**
  [`app/demo/empty-candles.tsx`](https://github.com/brandtnewlabs/react-native-livechart/blob/main/app/demo/empty-candles.tsx)
  switches between moving line and candlestick charts while a simulated trade
  feed continues. Compare raw sparse data, forward-fill, semantic-default, and
  custom-styled treatments. The **Styled** treatment exposes section toggles,
  independent colors, bridge paint, band fill/border/dashes, and label
  placement. Use **Live trades** to pause the feed for inspection.
</Note>

```tsx theme={null}
import { LiveChart, type ChartGap } from "react-native-livechart";

const gaps: ChartGap[] = [
  {
    from: maintenanceStart,
    to: maintenanceEnd,
    kind: "unavailable",
    label: "Exchange maintenance",
  },
];

<LiveChart data={points} value={liveValue} lineGaps={gaps} />;
```

The same metadata works in candlestick mode:

```tsx theme={null}
<LiveChart
  data={points}
  value={liveValue}
  mode="candle"
  candles={candles}
  liveCandle={liveCandle}
  candleWidth={60}
  candleGaps={gaps}
/>
```

## Semantic states

| Kind            | Default price treatment                          | Default market-state treatment          |
| --------------- | ------------------------------------------------ | --------------------------------------- |
| `"no-trades"`   | Flat bridge at the previous observed value/close | No time band                            |
| `"unavailable"` | Flat previous-value/close bridge                 | Shaded time band with an optional label |
| `"unknown"`     | No forward-filled price                          | Shaded time band with an optional label |

The library never infers a reason from sparse timestamps. With no gap prop, a line retains its
normal interpolation across missing timestamps and a candle chart retains its normal empty space.
Real samples or candles take precedence when they conflict with a declared range.

## Styling

Both props accept the same `ChartGapsConfig` object. Override one or more semantic styles:

```tsx theme={null}
<LiveChart
  data={points}
  value={liveValue}
  lineGaps={{
    gaps,
    styles: {
      unavailable: {
        bridge: { color: "#f59e0b", strokeWidth: 2 },
        band: {
          fillColor: "#78350f",
          fillOpacity: 0.14,
          borderColor: "#f59e0b",
          borderOpacity: 0.8,
          borderWidth: 1,
          intervals: [5, 4],
        },
        label: { color: "#fef3c7", position: "left" },
      },
      unknown: {
        bridge: false,
        band: { fillOpacity: 0.08 },
      },
    },
  }}
/>
```

Each nested section can be set to `false` to disable it, omitted to keep that gap kind's semantic
default, or set to an object to enable it and override its paint. For example,
`{ bridge: {}, band: false, label: false }` gives a forward-fill-only treatment. This preserves
time spacing but is intentionally ambiguous; prefer a labeled `"unavailable"` band when downtime
is known. A gap with no preceding real observation cannot be price-bridged.

## Renderer behavior

Line mode splits the main stroke, gradient/area fill, dot-lattice fill, and threshold fill into
separate subpaths at every declared empty interval. This prevents the normal spline or straight
segment from implying trades through an outage. A bridge is drawn independently on top, so its
color, opacity, width, and cap do not change the normal line style.

Candle mode emits zero-height previous-close marks for fully covered, actually missing buckets.
Those generated marks carry no volume and do not affect momentum, axis range, or extrema labels.

## Timeframes and partial buckets

Gap ranges use absolute `[from, to)` Unix-second intervals. Candle marks are re-bucketed from
`candleWidth`, so the same metadata works across timeframe changes. Only fully covered, actually
missing buckets receive a mark. A partial outage within a bucket can still show a time band, but it
does not turn a bucket containing trades into an empty candle.

Line gaps are not bucketed: their boundaries map directly to time on the x-axis. A real line point
inside the range makes that gap inert so the library never hides observed data.

## Scrubbing

The built-in tooltip shows a gap's custom `label` (or its semantic default) and time. A bridged gap
also anchors the selection dot and numeric scrub value at the last observation; an unbridged gap
remains price-free. In candle mode, `scrub.snapToCandles` also snaps across explicit `"no-trades"`
buckets.

Custom tooltips receive `ctx.gap: SharedValue<ChartGap | null>`. The JS-thread `onScrub` payload
includes `gap` when the gap supplies a previous value. Unbridged gaps—including `"unknown"` by
default—do not emit a fabricated numeric scrub value.

See [Candlestick](/guides/candlestick) for OHLC input, volume, sizing, and normal candle styling.