useStreamingViewport

The useStreamingViewport hook is similar to useStreamingData but includes automatic viewport (x-axis domain) management. It's ideal for charts that need to show a moving window of time-series data.

Used in components: Not used internally by Once UI components

This is a utility hook for building custom real-time data visualizations with dynamic viewport adjustment. Use it when you need charts where the x-axis automatically scrolls with incoming data, such as live monitoring dashboards.

Features

Smooth data interpolation
Automatic viewport adjustment
Sliding window with dynamic x-domain
Pause/resume streaming
Reset functionality
RequestAnimationFrame-based updates

Basic usage

Create a streaming chart with auto-adjusting viewport:

StreamingViewportChart.tsx

import { useStreamingViewport } from '@once-ui-system/core';
import { LineChart } from '@once-ui-system/core/data';

type Point = { time: number; value: number };

function StreamingViewportChart() {
const { data, xDomain, running, setRunning } = useStreamingViewport<Point>({
  initialData: generateInitialData(),
  windowSize: 20,
  intervalMs: 1000,
  xKey: 'time',
  numericKeys: ['value'],
  getNextTarget: ({ lastPoint, nextX }) => ({
    value: Math.random() * 100
  })
});

return (
  <div>
    <button onClick={() => setRunning(!running)}>
      {running ? 'Pause' : 'Resume'}
    </button>
    <LineChart
      xAxisType="number"
      xDomain={xDomain}
      animation={false}
      series={[{ key: "value" }]}
      data={data}
    />
  </div>
);
}

Real-time metrics

Monitor live system metrics with moving viewport:

LiveMetrics.tsx

function LiveMetrics() {
const { data, xDomain, running, setRunning, reset } = useStreamingViewport({
  initialData: Array.from({ length: 30 }, (_, i) => ({
    timestamp: Date.now() - (30 - i) * 1000,
    requests: 100 + Math.random() * 50,
    errors: Math.random() * 5,
    latency: 50 + Math.random() * 100
  })),
  windowSize: 30,
  intervalMs: 1000,
  xKey: 'timestamp',
  numericKeys: ['requests', 'errors', 'latency'],
  getNextTarget: ({ lastPoint }) => ({
    requests: Math.max(0, lastPoint.requests + (Math.random() - 0.5) * 30),
    errors: Math.max(0, lastPoint.errors + (Math.random() - 0.5) * 2),
    latency: Math.max(0, lastPoint.latency + (Math.random() - 0.5) * 40)
  })
});

return (
  <Flex direction="column" gap="16">
    <Flex gap="8">
      <Button onClick={() => setRunning(!running)}>
        {running ? 'Pause' : 'Resume'}
      </Button>
      <Button onClick={reset}>Reset</Button>
    </Flex>
    <LineChart
      xAxisType="number"
      xDomain={xDomain}
      animation={false}
      series={[{ key: "requests" }, { key: "errors" }, { key: "latency" }]}
      data={data}
    />
  </Flex>
);
}

API Reference

	Type	Default
initialData	T[]	—
windowSize	number	—
intervalMs	number	—
stepMs	number	16
xKey	keyof T	—
numericKeys	Array<keyof T>	—
getNextTarget	({ lastPoint, nextX }) => Partial<T>	—

Return value

Return type

{
data: T[];                                    // Current data window
xDomain: [number, number];                    // X-axis domain [min, max]
running: boolean;                             // Whether streaming is active
setRunning: (running: boolean) => void;       // Control streaming state
reset: () => void;                            // Reset to initial data
}

Difference from useStreamingData

The key difference is the xDomain return value:

useStreamingData: Returns only data
useStreamingViewport: Returns data + xDomain for chart axis

Use useStreamingViewport when you need the chart viewport to move with the data.

Example with timestamps

TimestampChart.tsx

function TimestampChart() {
const { data, xDomain, running, setRunning } = useStreamingViewport({
  initialData: Array.from({ length: 20 }, (_, i) => ({
    timestamp: Date.now() - (20 - i) * 2000,
    temperature: 20 + Math.random() * 5,
    humidity: 60 + Math.random() * 10
  })),
  windowSize: 20,
  intervalMs: 2000,
  xKey: 'timestamp',
  numericKeys: ['temperature', 'humidity'],
  getNextTarget: ({ lastPoint }) => ({
    temperature: lastPoint.temperature + (Math.random() - 0.5) * 2,
    humidity: lastPoint.humidity + (Math.random() - 0.5) * 5
  })
});

return (
  <LineChart
    xAxisType="number"
    xDomain={xDomain}
    series={[{ key: "temperature" }, { key: "humidity" }]}
    data={data}
  />
);
}

Performance considerations

Uses requestAnimationFrame for smooth animations
Automatically pauses when running is false
Cleans up on unmount
Efficient sliding window implementation

Use cases

Real-time dashboards: System monitoring, analytics
Live data feeds: Stock prices, sensor data
Performance monitoring: Server metrics, application stats
IoT dashboards: Temperature, humidity, sensor readings

useStreamingData - Similar but without viewport management