matterviz

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, XRD), 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" />

Composition

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

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

Trajectory

<script>
  import { Trajectory } from 'matterviz'
  // supports .xyz/.extxyz, .traj, .hdf5, .npz, .pkl, .dat, .gz, .zip, .bz2, .xz
</script>

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

🧪   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.ts 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-01-23},
  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-01-23}, % optional, replace with your date of access
  version = {0.3.1}, % replace with the version you use
}