# Chart — SvelteKit UI

Package: sveltekit-ui 1.1.94

Page: https://www.sveltekit-ui.com/components/chart

Category: Data & content

Renders a time-series chart with multiple frames, shared y axes, candlesticks, points, paths, or straight lines; supports pan, zoom, and hover inspection.

Public component import: `Chart`

Public manager import: `create_chart_manager`

## Component notes

- data_shapes:
  - chart: { id: string, x_axis_type: 'time', x_axis_title?: string, shown_start_x?: number, shown_end_x?: number, frames: Frame[] }. X coordinates and bounds use Unix seconds; shown_end_x is exclusive for points/path/klines. Axis tick formatting currently treats x as time.
  - frame: { aspect_ratio: positive number, shown_y_axis_index: integer (usually 0), shared_y_axiss: SharedYAxis[] }. aspect_ratio is width/height.
  - shared_y_axis: { y_axis_type: 'price' | 'pd' | 'number', y_axis_title?: string, top_padding_pd?: number, bottom_padding_pd?: number, manual_low_y?: number, manual_high_y?: number, datasets: DatasetDescriptor[] }. Padding defaults to 0.2 and is clamped to 0..0.45. Manual bounds require high > low.
  - dataset_descriptor: { type: 'klines' | 'points' | 'path' | 'lines', dataset_id: string, name?: string, period_x: positive number of seconds, keys: string[], colors: Color[], affects_y_scale?: boolean }. colors must be an array; an empty array uses fallback colors. affects_y_scale defaults to true except for lines.
  - keys: For points/path: [x_key, y_key]. For klines: [x_key, open_key, low_key, high_key, close_key]. For lines: [slope_key, intercept_key, optional_metadata_key], describing y = m*x+b; the optional third value is carried as s metadata. Sort raw data by x for an ordered path.
  - color: { l: number, c: number, h: number, o?: number, is_theme_based?: boolean }. Values select the library's numbered lightness/chroma/hue/opacity tokens; they are not raw OKLCH coordinates.
- notes:
  - Chart measures its container in the browser before preparing plotted data; chart_prepped is unavailable during server rendering. Provide a container with usable width.

## Usage

```svelte
<script>
  // Import the shared stylesheet once in your application's root layout.
  import "sveltekit-ui/style.css"
  import { Chart, create_chart_manager } from "sveltekit-ui"

  // Chart x values are Unix timestamps in seconds.
  const datasets = {
    visitors: {
      data: [
        { timestamp: 1791417600, count: 24 },
        { timestamp: 1791504000, count: 38 },
        { timestamp: 1791590400, count: 31 },
        { timestamp: 1791676800, count: 52 },
      ],
    },
  }
  const chart = {
    id: "visitors-chart",
    x_axis_type: "time",
    x_axis_title: "Day",
    // The end boundary is exclusive; include the final point in the range.
    shown_start_x: 1791417600,
    shown_end_x: 1791763200,
    frames: [{
      aspect_ratio: 2,
      shown_y_axis_index: 0,
      shared_y_axiss: [{
        y_axis_type: "number",
        y_axis_title: "Visitors",
        top_padding_pd: 0.2,
        bottom_padding_pd: 0.2,
        datasets: [{
          type: "path",
          name: "Daily visitors",
          dataset_id: "visitors",
          keys: ["timestamp", "count"],
          period_x: 86400,
          colors: [{ l: 10, c: 12, h: 16, o: 24, is_theme_based: true }],
        }],
      }],
    }],
  }

  const manager = create_chart_manager({ chart, datasets })
</script>

<div style="width: 100%; max-width: 80rem;">
  <Chart {manager} />
</div>
<p>Drag to pan, scroll to zoom, or drag the y axis to change its range.</p>
```

## Configuration

### `datasets`

- type: object
- required: true
- description: Records keyed by dataset_id, each containing { data: object[] }. Raw point keys are mapped by each chart dataset descriptor. Optional y_min/y_max affect straight-line scaling.

### `chart`

- type: object
- required: true
- description: Chart configuration with id, x_axis_type, x_axis_title, optional shown_start_x/shown_end_x, and frames. Use the exact nested shapes below, including the shared_y_axiss spelling.

### `range_to_show_default`

- type: number
- default: 500
- description: Approximate count of points used to choose the initial x range when a dataset has more than 20 points. Explicit shown_start_x/shown_end_x override this range.

### `min_visible_bars`

- type: number
- default: 20
- description: Minimum visible period count during zoom; uses the smallest positive period_x among chart descriptors.

### `x_edge_padding_ratio`

- type: number
- default: 0.5
- description: Extra scrollable x range at either edge, as a fraction of the visible range.

## Methods

### `set_datasets()`

- parameters:
  - input: dataset records
- returns: void
- description: Replace raw datasets. Call refresh_chart() afterward to recompute the plot.

### `refresh_chart()`

- parameters:
  - opts: { keep_view?: boolean } (default keep_view: true)
- returns: void
- description: Recompute the chart from current data and width. Set keep_view false to reset the x range. Does nothing before a usable width/datasets exists.

### `set_grid_width()`

- parameters:
  - input: number (CSS pixels)
- returns: void
- description: Set measured chart width; the Chart component does this automatically.

### `gen_color()`

- parameters:
  - l: number
  - c: number
  - h: number
  - o: number = 16
  - is_theme_based: boolean = true
  - dark_l_offset: number = 0
  - is_dark_theme: boolean = true
  - is_safari: boolean = false
- returns: string
- description: Generate a theme-token color for chart rendering.

### `handle_scroll_frame()`

- parameters:
  - event: DOM wheel, pointer, or mouse event
  - frame_index: number (where used)
- returns: void
- description: Rendering event handler wired by Chart; prefer the component's built-in interactions.

### `handle_pointer_down()`

- parameters:
  - event: DOM wheel, pointer, or mouse event
  - frame_index: number (where used)
- returns: void
- description: Rendering event handler wired by Chart; prefer the component's built-in interactions.

### `handle_pointer_move()`

- parameters:
  - event: DOM wheel, pointer, or mouse event
  - frame_index: number (where used)
- returns: void
- description: Rendering event handler wired by Chart; prefer the component's built-in interactions.

### `handle_pointer_up()`

- parameters:
  - event: DOM wheel, pointer, or mouse event
  - frame_index: number (where used)
- returns: void
- description: Rendering event handler wired by Chart; prefer the component's built-in interactions.

### `handle_pointer_cancel()`

- parameters:
  - event: DOM wheel, pointer, or mouse event
  - frame_index: number (where used)
- returns: void
- description: Rendering event handler wired by Chart; prefer the component's built-in interactions.

### `handle_y_axis_pointer_down()`

- parameters:
  - event: DOM wheel, pointer, or mouse event
  - frame_index: number (where used)
- returns: void
- description: Rendering event handler wired by Chart; prefer the component's built-in interactions.

### `handle_y_axis_pointer_move()`

- parameters:
  - event: DOM wheel, pointer, or mouse event
  - frame_index: number (where used)
- returns: void
- description: Rendering event handler wired by Chart; prefer the component's built-in interactions.

### `handle_y_axis_pointer_up()`

- parameters:
  - event: DOM wheel, pointer, or mouse event
  - frame_index: number (where used)
- returns: void
- description: Rendering event handler wired by Chart; prefer the component's built-in interactions.

### `handle_y_axis_pointer_cancel()`

- parameters:
  - event: DOM wheel, pointer, or mouse event
  - frame_index: number (where used)
- returns: void
- description: Rendering event handler wired by Chart; prefer the component's built-in interactions.

### `handle_scroll_y_axis()`

- parameters:
  - event: DOM wheel, pointer, or mouse event
  - frame_index: number (where used)
- returns: void
- description: Rendering event handler wired by Chart; prefer the component's built-in interactions.

### `handle_chart_hover()`

- parameters:
  - event: DOM wheel, pointer, or mouse event
  - frame_index: number (where used)
- returns: void
- description: Rendering event handler wired by Chart; prefer the component's built-in interactions.

### `handle_chart_hover_leave()`

- parameters:
  - event: DOM wheel, pointer, or mouse event
  - frame_index: number (where used)
- returns: void
- description: Rendering event handler wired by Chart; prefer the component's built-in interactions.

### `handle_y_axis_click()`

- parameters:
  - frame_index: number
- returns: void
- description: Cycle the selected shared y axis for a frame, suppressing the click after a drag.

## Returned state

### `datasets`

- type: object
- description: Current raw dataset records.

### `chart_prepped`

- type: object | null | undefined
- description: Prepared chart with frames, normalized datasets, ticks, hover state, current shown_start_x/shown_end_x, all_data_start_x/all_data_end_x, and range setters. Unavailable until measured.

### `grid_width`

- type: number | null
- description: Measured container width in CSS pixels.

### `frame_width`

- type: number
- description: Measured width less the 70px y axis.

### `y_axis_width`

- type: number
- description: Y axis allocation: 70 CSS pixels.

### `x_axis_height`

- type: number
- description: X axis allocation: 30 CSS pixels.

### `period_to_sec`

- type: object
- description: Built-in period label to seconds map, from 5m through 2w.
