QuirkVis JS

A highly customizable Quantum Circuit SVG Visualizer for the Web and Node.js. This is a JavaScript/TypeScript reimplementation of the quantum_quirkvis Python library.

Features

• OpenQASM 3 Support: Handles gates, registers, measurements, and barriers.
• Highly Customizable: Uses JSON-based themes to control every aspect of the circuit's appearance.
• Multiple Themes Included: Default, Emoji, Matrix, and Night.
• Responsive: Support for fitting to container and arbitrary zoom levels.
• Interactive Mode: Hover over gates and moments with visual highlighting and receive detailed element info via callbacks.
• Lightweight: Optimized for performance in both browser and server environments.

Quick Start

Installation

npm install @ljcamargo/quirkvis-react

Usage in React

import { QuirkVis } from '@ljcamargo/quirkvis-react';
import { themes } from '@ljcamargo/quirkvis-core';

const qasmString = `
OPENQASM 3.0;
include "stdgates.inc";
qubit[2] q;
h q[0];
cx q[0], q[1];
`;

function App() {
  return (
    <QuirkVis 
      qasm={qasmString} 
      theme={themes.default} 
      fitWidth={true}   // Scale to fit container width
      fitHeight={false}  // Scale to fit container height
      zoom={1.0}        // Manual scale (ignored if fitWidth/Height is true)
      interactive={true} // Enable hover highlighting
      onHover={(info) => console.log(info)}
    />
  );
}

QuirkVis Props

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | qasm | string | Required | The OpenQASM 3.0 source code. | | theme | Theme | Required | A theme object (e.g., from themes). | | fitWidth | boolean | false | Scale the circuit to fit the container width. | | fitHeight | boolean | false | Scale the circuit to fit the container height. | | zoom | number | 1 | Zoom multiplier (only used if fitWidth AND fitHeight are false). | | interactive | boolean | false | Enable hover highlighting and element detection via data-qv-* attributes. | | onHover | (info: HoverInfo) => void | undefined | Callback fired when hovering over gates, moments, wires, or labels. | | className| string | undefined | CSS class for the wrapper div. | | style | CSSProperties | undefined | Inline styles for the wrapper div. |

Interactive Mode

When interactive={true}, the circuit responds to hover:

• Moment columns highlight with a tinted rectangle spanning the circuit height.
• Gates brighten and saturate their fill color with an increased stroke — the containing moment column highlights simultaneously.
• Every element gets data-qv-* attributes (data-qv-gate, data-qv-moment, data-qv-qubits, etc.) for custom styling or programmatic detection.
• Text selection is disabled and gate labels don't block hover events.

Callback behavior: the onHover callback always carries momentIndex — even when a gate is hovered, its containing moment index is reported alongside the gate name and qubits. The HoverInfo.type distinguishes whether the hover originated from a gate ('gate'), a moment background ('moment'), or another element.

Hover Callback

import { useState } from 'react';
import { QuirkVis } from '@ljcamargo/quirkvis-react';
import type { HoverInfo } from '@ljcamargo/quirkvis-react';
import { themes } from '@ljcamargo/quirkvis-core';

function App() {
  const [hovered, setHovered] = useState<HoverInfo | null>(null);

  return (
    <div>
      <QuirkVis 
        qasm={qasmString}
        theme={themes.default}
        fitWidth={true}
        interactive={true}
        onHover={setHovered}
      />
      {hovered && hovered.type !== 'none' && (
        <p>{hovered.gateName?.toUpperCase()} on {hovered.qubits?.join(', ')} (moment {hovered.momentIndex})</p>
      )}
    </div>
  );
}

HoverInfo Type

interface HoverInfo {
  type: 'moment' | 'gate' | 'barrier' | 'measure' | 'connection' | 'wire' | 'label' | 'none';
  momentIndex: number;
  lineIndex?: number;      // For wires and labels
  gateName?: string;       // For gates (e.g. 'h', 'cx', 'rx')
  qubits?: string[];       // For gates (e.g. ['q[0]', 'q[1]'])
  label?: string;          // For labels (e.g. 'q[0]', 'c')
}

When the mouse leaves the circuit, `onHover` fires with `{ type: 'none', momentIndex: -1 }`.

## Development

This project uses [Bun](https://bun.sh) for development.

```bash
# Install dependencies
bun install

# Build all packages
bun run build

# Run the sample demo app
bun run sample

License

MIT