Repository files navigation

matterviz is a toolkit for building interactive web UIs for materials science: periodic tables, 3d crystal structures (and molecules, though needs some improvements!), Bohr atoms, nuclei, heatmaps, scatter plots. It's under active development and not yet ready for production use but we appreciate any feedback from beta testers! 🙏

Visualize crystal structures, molecules, and molecular dynamics trajectoriesdirectly 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 - seeConfiguration Guide for examples

• ✅ MatterViz Web:matterviz.janosh.dev (works but under active development)
• ✅ MatterViz VSCode:marketplace.visualstudio.com/items?itemName=janosh.matterviz (works but under active development)
• ✅ pymatviz:Jupyter/Marimo extension for Python notebooks. Read about widgets inpymatviz readme for details.

This screenshot demonstrates the periodicity of elemental properties (i.e. why it's called periodic table). In this case, you're seeing recurring bumps and valleys in the first ionization energy as a function of atomic number.

The details page for gold.

npm install --dev matterviz

<script>import {PeriodicTable }from'matterviz'constheatmap_values= {H:10, He:4, Li:8, Fe:3,O:24 }</script><PeriodicTable {heatmap_values} />

<script>import {Structure }from'matterviz'constdata_url='/structures/TiO2.cif'// supports .cif, .poscar, .xyz/.extxyz, pymatgen JSON, OPTIMADE JSON, .gz</script><Structure {data_url}style="width: 500px; aspect-ratio: 1" />

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

<script>import {Trajectory }from'matterviz'// supports .xyz/.extxyz, .traj, .hdf5, .npz, .pkl, .dat, .gz, .zip, .bz2, .xz</script><Trajectorydata_url="/traj/ase-md.xyz"auto_playfps={10}style="max-height: 700px" />

Statements	Branches	Lines

• Element properties insrc/lib/element-data.ts were combined fromBowserinator/Periodic-Table-JSON under Creative Commons license androbertwb/Periodic Table of Elements.csv (unlicensed).
• Thanks toImages of Elements for providing photos of elemental crystals and glowing excited gases.
• Thanks to@kadinzhang and theirPeriodicity 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. Seefetch-elem-images.ts andstatic/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:

Usecitation.cff or cite theZenodo record using the following BibTeX entry:

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