A 3D Bloch Sphere visualisation built with Three.js and TypeScript.
npm install @qbead/bloch-sphereA 3D Bloch sphere visualization library built with Three.js.


- Interactivity: Ability to rotate the sphere with mouse/touch.
- Quantum State Operations: Quantum gates (Pauli, Hadamard, rotation gates)
- Math Library: Complex number and operator algebra
- Type-Safe: Written in TypeScript with full type definitions
- Flexible Components: Modular display components (arrows, paths, regions, labels, points)
- Animation Support: Smooth interpolation between quantum states
Live Demo: bloch-sphere.qbead.org
``sh`
bun install @qbead/bloch-sphere three
The library requires Three.js as a peer dependency.
`typescript
import { BlochSphere, BlochVector, QubitDisplay } from '@qbead/bloch-sphere'
// Initialize the Bloch sphere
const sphere = new BlochSphere({
fontSize: 1.25,
showGrid: true,
})
// Attach to the DOM
sphere.attach(document.body)
// Create and display a quantum state (|+⟩ state)
const qubit = new QubitDisplay(BlochVector.PLUS)
sphere.add(qubit)
`
`typescript
import { BlochVector, gates } from '@qbead/bloch-sphere'
// Start with |0⟩ state
const state = BlochVector.ZERO
// Apply Hadamard gate to create superposition
const hadamardGate = gates.hadamard()
const superposition = state.applyOperator(hadamardGate)
// Apply Pauli-X gate (bit flip)
const xGate = gates.x()
const flipped = superposition.applyOperator(xGate)
`
`typescript
import { Complex } from '@qbead/bloch-sphere'
// Create complex numbers
const a = new Complex(3, 4) // 3 + 4i
const b = Complex.fromPolar(1, Math.PI / 4) // e^(iπ/4)
// Complex arithmetic
const sum = a.plus(b)
const product = a.times(b)
const magnitude = a.magnitude // |a| = 5
const phase = a.phase // arg(a)
`
`typescript
import { Operator, Complex } from '@qbead/bloch-sphere'
// Create a custom 2x2 operator matrix
const customOperator = new Operator([
[new Complex(1, 0), new Complex(0, -1)],
[new Complex(0, 1), new Complex(1, 0)],
])
// Verify unitarity
const identity = customOperator
.conjugateTranspose()
.times(customOperator)
// Apply to quantum state
const newState = state.applyOperator(customOperator)
`
`typescript
import { gates, BlochVector } from '@qbead/bloch-sphere'
// Rotate around X-axis by π/4
const rxGate = gates.rx(Math.PI / 4)
// Rotate around Y-axis by π/2
const ryGate = gates.ry(Math.PI / 2)
// Rotate around Z-axis (phase rotation)
const rzGate = gates.rz(Math.PI / 3)
// Apply rotation
const rotated = BlochVector.ZERO.applyOperator(rxGate)
`
`typescript
import { BlochSphere, BlochVector, PathDisplay, gates } from '@qbead/bloch-sphere'
const sphere = new BlochSphere()
sphere.attach(document.body)
// Create a sequence of states
const states = [
BlochVector.ZERO,
BlochVector.ZERO.applyOperator(gates.hadamard()),
BlochVector.ZERO.applyOperator(gates.hadamard()).applyOperator(gates.z()),
]
// Display as a path
const path = new PathDisplay(states)
path.color = 0x00ff00
sphere.add(path)
`
For complete API documentation, visit: qbead.gitbook.io/bloch-sphere
See qbead.gitbook.io/bloch-sphere for complete reference.
- Main 3D visualization container
- QubitDisplay - Display individual qubit states
- PathDisplay - Show paths between quantum states
- OperatorDisplay - Visualize operator transformations$3
- BlochVector - Quantum state representation on Bloch sphere
- Complex - Complex number arithmetic
- Operator - 2x2 matrix operators for quantum gates
- gates - Standard quantum gates (X, Y, Z, H, rotation gates)$3
- BlochVector.ZERO - |0⟩ state
- BlochVector.ONE - |1⟩ state
- BlochVector.PLUS - |+⟩ state (superposition)
- BlochVector.MINUS - |−⟩ state
- BlochVector.I - |i⟩ state
- BlochVector.MINUS_I - |−i⟩ state
Development
`sh
Install dependencies
bun installRun tests
bun testRun tests with coverage
bun test:coverageBuild the library
bun run buildType checking
bun run typecheck
`Test Coverage
Run
bun test:coverage` to see detailed coverage reports.The library works in all modern browsers that support WebGL (required for Three.js).
MIT © Jasper Palfree
Contributions are welcome! Please feel free to submit issues or pull requests on GitHub.
Work commisioned by the Qbead team!