Matterviz

<h1 align="center"> _{<img src="static/favicon.svg" alt="Logo" width="40px">} MatterViz </h1> <h4 align="center">

</h4>

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 (<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>v</kbd> on Windows, <kbd>cmd</kbd>+<kbd>shift</kbd>+<kbd>v</kbd> 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
}