MatterViz
[](https://github.com/janosh/matterviz/actions/workflows/test.yml)
[](https://github.com/janosh/matterviz/actions/workflows/gh-pages.yml)
[](https://marketplace.visualstudio.com/items?itemName=janosh.matterviz)
[](https://matterviz.janosh.dev)
[](https://stackblitz.com/github/janosh/matterviz)
[](https://doi.org/10.5281/zenodo.17094509)
`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](extensions/vscode/readme.md#οΈ-configuration--customization) for examples
[matterviz vscode extension]: https://marketplace.visualstudio.com/items?itemName=janosh.matterviz
## πΊοΈ Roadmap
- **β
MatterViz Web**: [matterviz.janosh.dev](https://matterviz.janosh.dev)
- **β
MatterViz VSCode/Cursor**: [marketplace.visualstudio.com/items?itemName=janosh.matterviz](https://marketplace.visualstudio.com/items?itemName=janosh.matterviz)
- **β
pymatviz**: [Jupyter](https://jupyter.org)/[Marimo](https://marimo.io) widgets for Python notebooks. See [`pymatviz` readme](https://github.com/janosh/pymatviz/blob/main/readme.md#interactive-widgets).
## βοΈ 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
```sh
npm add -D matterviz
```
## π Usage
### Periodic Table
```svelte
```
### Structure
```svelte
```
### Composition
```svelte
```
### Trajectory
```svelte
```
## π§ͺ Coverage
| Statements | Branches | Lines |
| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|  |  |  |
## π Acknowledgements
- Element properties in `src/lib/element/data.ts` were combined from [`Bowserinator/Periodic-Table-JSON`](https://github.com/Bowserinator/Periodic-Table-JSON/blob/master/PeriodicTableJSON.json) under Creative Commons license and [`robertwb/Periodic Table of Elements.csv`](https://gist.github.com/robertwb/22aa4dbfb6bcecd94f2176caa912b952) (unlicensed).
- Thanks to [Images of Elements](https://images-of-elements.com) for providing photos of elemental crystals and glowing excited gases.
- Thanks to [@kadinzhang](https://github.com/kadinzhang) and their [Periodicity project](https://ptable.netlify.app) [[code](https://github.com/kadinzhang/Periodicity)] 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`](https://github.com/janosh/matterviz/blob/-/src/scripts/fetch-elem-images.ts) and [`static/elements`](https://github.com/janosh/matterviz/tree/main/static/elements).
- Thanks to [@ixxie](https://github.com/ixxie) ([shenhav.fyi](https://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](https://threejs.org) | [d3](https://d3js.org) | [mdsvex](https://mdsvex.com) | [vite](https://vitejs.dev) | [playwright](https://playwright.dev) |
| [threlte](https://threlte.xyz) | [sharp](https://sharp.pixelplumbing.com) | [rehype](https://github.com/rehypejs/rehype) | [sveltekit](https://kit.svelte.dev) | [vitest](https://vitest.dev) |
## How to cite `matterviz`
Use [`citation.cff`](citation.cff) or cite the [Zenodo record](https://zenodo.org/badge/latestdoi/498793280) 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.3.1}, % replace with the version you use
}
```