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][MatterViz VSCode Extension]. 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

[matterviz vscode extension]: https://marketplace.visualstudio.com/items?itemName=janosh.matterviz

🗺️   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.

!Landing page showing 3D structure viewers

⚛️   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.

!3D Structure Viewer

📊   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.

!Periodic table heatmap

🔬   Element Details Pages

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

!Element details page for gold

🔨   Installation

``sh
npm install --dev matterviz
`

📙   Usage

$3

`svelte



`

$3

`svelte



`

$3

`svelte



`

$3

`svelte



`

🧪   Coverage

| Statements | Branches | Lines |
| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| !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:

`bib
@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.2.2}, % replace with the version you use
}
``