Data Display

Waveform

Responsive SVG rendering of time-domain audio amplitude data as a waveform path or bar display.

import { Waveform } from '@lostgradient/cinder/waveform';
chartwaveformsignalaudio
01

Overview

Responsive SVG rendering of time-domain audio amplitude data as a waveform path or bar display.

Usage

svelte 
<script lang="ts">
  import Waveform from '@lostgradient/cinder/waveform';
</script>

<Waveform label="Voice recording waveform" data={[]} height={80}>
  {#snippet empty()}
    No recording captured yet.
  {/snippet}
</Waveform>

Guidance

Use When

  • Visualizing pre-recorded or pre-processed audio amplitude samples in a static display.
  • Showing an audio waveform thumbnail or preview with mocked or pre-computed sample data.

Avoid When

  • Real-time live audio capture is needed — wire AudioContext / AnalyserNode yourself and feed samples as props.
  • Frequency-domain data — use spectrum-chart or spectrogram instead.

Rendering and theming

Waveform uses SVG, inherits its foreground from currentColor, defaults its background to transparent, and resolves the path or bars through the first --cinder-chart-series-* color. Pass a partial theme to override the palette or chart colors, including the rendered chart background. Buffers above 2,000 rendered points use a min/max envelope so peaks remain visible without creating an unbounded SVG; the data-table caption reports when its readable sample is truncated.

Live preview
02

When to use

Use when
  • Visualizing pre-recorded or pre-processed audio amplitude samples in a static display.
  • Showing an audio waveform thumbnail or preview with mocked or pre-computed sample data.
Avoid when
  • Real-time live audio capture is needed — wire AudioContext / AnalyserNode yourself and feed samples as props.
  • Frequency-domain data — use spectrum-chart or spectrogram instead.
03

Examples

Audio waveform (bars mode)

Pre-computed audio amplitude samples rendered as vertical amplitude bars.

Empty state

When `data` is empty, supply an `empty` snippet to explain the absence instead of rendering a flat, meaningless plot.

Loading state

While audio is being decoded, set `loading` and supply a `loadingContent` snippet to render a placeholder over the viewport instead of the plot.

Sine wave (path mode)

A time-domain sine wave rendered as a continuous SVG path.

04

Props

Props for waveform
NameTypeDefaultDescription
label required text Accessible label for the waveform. Required for screen readers.
description text Optional description rendered below the label.
data required number[] Time-domain amplitude samples. Each value should be in the range [-1, 1]. Values outside this range are clamped.
renderMode 'path' | 'bars' 'path' How to render the waveform: as a continuous path or vertical amplitude bars. Default path.
height number 80 Pixel height of the chart. Default 80.
loading boolean false Whether the waveform is in a loading state.
dataTableVisibility 'screen-reader-only' | 'visible' | 'hidden' 'screen-reader-only' Controls data table visibility. Default screen-reader-only.
dataTableCaption text Custom data table caption; falls back to label.
theme ChartTheme Partial visual theme override. Omitted fields inherit the surrounding application.
empty snippet Snippet rendered when the chart has no data.
loadingContent snippet Snippet rendered while loading.
id text