# Frequency chart

> Frequency response on a log axis: a spectrum, or a Bode plot with gain and phase margins drawn where they are measured.

Category: Charts · Atomic level: organism
Page: https://ui.dtheo.dev/docs/charts/frequency-chart

## Install

```bash
npx dtheo@latest add frequency-chart
# or, with the shadcn CLI
npx shadcn@latest add https://ui.dtheo.dev/r/frequency-chart.json
```

Dependencies: d3-scale. Registry dependencies: none.

## Exports

`FrequencyChart`

## Use it for

- Bode plots of a control loop, with crossover and margins
- Vibration and noise spectra with labelled peaks

## Reach for something else

- Signals over time: use Line chart
- A handful of frequencies people compare exactly: use a Table

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `frequency` | `ArrayLike<number>` | – | Frequencies in Hz, ascending and above zero. |
| `magnitude` | `FrequencySeries[]` | – | Magnitude series in dB (or the unit in `magnitudeUnit`). |
| `phase` | `FrequencySeries[]` | – | Phase series in degrees. Adds a second pane: a Bode plot. |
| `spans` | `FrequencySpan[]` | – | Vertical arrows between a value and a reference, for gain and phase margins. |
| `peaks` | `FrequencyPeak[]` | – | Labelled points on the magnitude pane, such as resonances. |
| `references` | `{ magnitude?: number[]; phase?: number[] }` | – | Dashed reference lines, such as 0 dB and −180°. |

## Keyboard

| Keys | Action |
| --- | --- |
| Arrow left / right | Move the readout to the next frequency |
| Shift + arrow | Move by a tenth of the range |
| Home / End | Jump to the lowest or highest frequency |
| Escape | Hide the readout |

## Accessibility

- Both panes share one crosshair and one readout, announced politely as you move.
- Decades are labelled (10, 100, 1k Hz); the steps between them are faint grid lines.
- Margins are labelled with their value, not shown by color.

## Examples

### frequency-chart

```tsx
import { FrequencyChart } from '@/components/charts/frequency-chart';
// Synthetic demo data: npx dtheo add lab-data, or pass your own.
import { bode } from '@/lib/lab-data';

const m = bode.margins;
const fmt = (v: number, d = 0) => v.toFixed(d);

export default function FrequencyChartExample() {
  return (
    <div className="flex w-full flex-col gap-3">
      <div className="flex flex-col">
        <span className="text-headline">Open-loop response</span>
        <span className="text-caption text-muted-foreground">
          RA-14 hip pitch · R-0412 against the R-0409 reference
        </span>
      </div>
      <FrequencyChart
        frequency={bode.frequency}
        magnitude={[
          { id: 'ref', label: 'R-0409', values: bode.reference.magnitude, tone: 'muted', width: 1.5 },
          { id: 'cur', label: 'R-0412', values: bode.current.magnitude },
        ]}
        phase={[
          { id: 'ref', label: 'R-0409', values: bode.reference.phase, tone: 'muted', width: 1.5 },
          { id: 'cur', label: 'R-0412', values: bode.current.phase },
        ]}
        magnitudeDomain={[-80, 30]}
        magnitudeTicks={[-60, -40, -20, 0, 20]}
        phaseDomain={[-315, -45]}
        phaseTicks={[-270, -180, -90]}
        references={{ magnitude: [0], phase: [-180] }}
        markers={[{ frequency: m.gainCrossover, label: `Crossover ${fmt(m.gainCrossover, 1)} Hz` }]}
        spans={[
          {
            pane: 'phase',
            frequency: m.gainCrossover,
            from: -180,
            to: m.phaseAtCrossover,
            label: `Phase margin ${fmt(m.phaseMargin)}°`,
          },
          {
            pane: 'magnitude',
            frequency: m.phaseCrossover,
            from: m.magnitudeAtPhaseCrossover,
            to: 0,
            label: `Gain margin ${fmt(m.gainMargin)} dB`,
          },
        ]}
        paneHeight={170}
        ariaLabel={`Bode plot. R-0412 crosses 0 dB at ${fmt(m.gainCrossover, 1)} Hz with a ${fmt(m.phaseMargin)}° phase margin, down from ${fmt(bode.referenceMargins.phaseMargin)}° on R-0409. Gain margin is ${fmt(m.gainMargin)} dB.`}
      />
    </div>
  );
}
```

### frequency-chart-spectrum

```tsx
import { FrequencyChart } from '@/components/charts/frequency-chart';
// Synthetic demo data: npx dtheo add lab-data, or pass your own.
import { spectrum } from '@/lib/lab-data';

export default function FrequencyChartSpectrumExample() {
  return (
    <div className="flex w-full flex-col gap-3">
      <div className="flex flex-col">
        <span className="text-headline">Vibration spectrum</span>
        <span className="text-caption text-muted-foreground">
          Output-flange accelerometer · R-0412 · 2 s capture
        </span>
      </div>
      <FrequencyChart
        frequency={spectrum.frequency}
        magnitude={[{ id: 'acc', label: 'Acceleration', values: spectrum.magnitude }]}
        magnitudeDomain={[-90, -10]}
        magnitudeTicks={[-80, -60, -40, -20]}
        magnitudeUnit="dB re 1 g"
        peaks={spectrum.peaks.filter((p) => p.value > -46)}
        paneHeight={220}
        ariaLabel="Vibration spectrum from 5 Hz to 1 kHz. The largest peak is the gearbox resonance at 182 Hz, near −22 dB; its harmonic at 364 Hz and motor cogging at 96 Hz sit about 20 dB lower."
      />
    </div>
  );
}
```

## Used in

- Loop tuning (page): https://ui.dtheo.dev/examples/tuning
