MatterViz

matterviz is a toolkit for building interactive web UIs for materials science: 3D crystal structures, molecules, MD/relaxation trajectories, periodic tables, phase diagrams, convex hulls, spectral data (bands, DOS, IR/Raman), diffraction and pair distribution functions (XRD, SAED, PDF/RDF), diffusion analysis (MSD), reaction paths (NEB), heatmaps, and scatter plots.

🔌   MatterViz VSCode Extension

Visualize crystal structures, molecules, and molecular dynamics trajectories directly in VSCode. Features include:

• Native support for common file formats (CIF, POSCAR, XYZ, TRAJ, HDF5, etc.)
• Context menu (right click > "Render with MatterViz") and keyboard shortcuts (ctrl+shift+v on Windows, cmd+shift+v on Mac) for quick access
• Custom viewer for MD trajectories/geometry optimizations
• Extensive customization options via VSCode settings - see Configuration Guide for examples

🗺️   Roadmap

• ✅ MatterViz Web: matterviz.janosh.dev
• ✅ MatterViz VSCode/Cursor: marketplace.visualstudio.com/items?itemName=janosh.matterviz
• ✅ pymatviz: Jupyter/Marimo widgets for Python notebooks. See pymatviz readme.

⚛️   3D Structure Viewer

Interactively visualize crystal structures and molecules. Supports drag-and-drop file loading for CIF, POSCAR, XYZ/EXTXYZ, pymatgen JSON, OPTIMADE JSON, and compressed formats.

📊   Periodic Table Heatmap

Visualize elemental properties across the periodic table. The inset scatter plot shows how properties vary with atomic number - here demonstrating the periodicity of first ionization energy.

🔬   Element Details Pages

Rich element pages with physical properties, electron configurations, Bohr atom visualizations, and element photos.

🔨   Installation

npm add -D matterviz

📙   Usage

Periodic Table

<script>
  import { PeriodicTable } from 'matterviz'

  const heatmap_values = { H: 10, He: 4, Li: 8, Fe: 3, O: 24 }
</script>

<PeriodicTable {heatmap_values} />

Structure

<script>
  import { Structure } from 'matterviz'
  const data_url = '/structures/TiO2.cif'
  // supports .cif, .poscar, .xyz/.extxyz, pymatgen JSON, OPTIMADE JSON, .gz
</script>

<Structure {data_url} style="width: 500px; aspect-ratio: 1" />

Structure renders whatever it is given: pass structure (a Crystal/Molecule you already hold), data_url (fetched and parsed, volumetric CHGCAR/cube files included) or structure_string. Selection, measurements, atom/bond editing with undo/redo and the supercell/image-atom pipeline live in a headless StructureSession (exported from matterviz/structure) that can be driven and tested without a DOM; active_pane: 'controls' | 'info' | 'export' | null is the one bindable that says which floating pane is open.

Composition

<script>
  import { Composition } from 'matterviz'
  // modes can be 'pie' (default) | 'bubble' | 'bar'
</script>

<Composition composition="LiFePO4" mode="pie" />

Trajectory

<script>
  import { TrajectoryFileViewer } from 'matterviz'
  // supports .xyz/.extxyz, .traj, .hdf5, .npz, .pkl, .dat plus .gz/.zip wrappers;
  // decompress .bz2/.xz first because browsers cannot decode them
</script>

<TrajectoryFileViewer src="/traj/ase-md.xyz" auto_play fps={10} style="max-height: 700px" />

TrajectoryFileViewer owns loading: it fetches src (a URL, File, ArrayBuffer or Blob), accepts drops, decompresses, resolves ambiguous HDF5 groups, opens files above DEFAULTS.trajectory.index_above_bytes in a Web Worker and disposes each run when it is replaced or the component unmounts. The Trajectory component underneath is a pure viewer that only borrows a TrajectoryRun you already hold, so pass trajectory={await open_trajectory(bytes, { filename })} (or trajectory_from_frames(frames)) when you manage the data yourself and call run.dispose() when done.

🧪   Coverage

Statements	Branches	Lines

🙏   Acknowledgements

• Element properties in src/lib/element/data.ts were combined from Bowserinator/Periodic-Table-JSON under Creative Commons license and robertwb/Periodic Table of Elements.csv (unlicensed).
• Thanks to Images of Elements for providing photos of elemental crystals and glowing excited gases.
• Thanks to @kadinzhang and their Periodicity project [code] for the idea to display animated Bohr model atoms and inset a scatter plot into the periodic table to visualize the periodic nature of elemental properties.
• Big thanks to all sources of element images. See fetch-elem-images.mjs and static/elements.
• Thanks to @ixxie (shenhav.fyi) for great suggestions.

This project would not have been possible as a one-person side project without many fine open-source projects. 🙏 To name just a few:

3D graphics	2D graphics	Docs	Bundler	Testing
three.js	d3	mdsvex	vite	playwright
threlte	sharp	rehype	sveltekit	vitest

How to cite matterviz

Use citation.cff or cite the Zenodo record using the following BibTeX entry:

@software{riebesell_matterviz_2022,
  title = {matterviz: visualization toolkit for materials informatics},
  author = {Riebesell, Janosh and Evans, Matthew},
  date = {2026-08-11},
  year = {2026},
  doi = {10.5281/zenodo.17094509},
  url = {https://github.com/janosh/matterviz},
  note = {10.5281/zenodo.17094509 - https://github.com/janosh/matterviz},
  urldate = {2026-08-11}, % optional, replace with your date of access
  version = {0.6.0}, % replace with the version you use
}