https://github.com/janosh/matterviz
Interactive browser visualizations for materials science: crystal structures/molecules, trajectories, convex hulls, phase diagrams, Fermi surfaces, bands+DOS, Brillouin zones, etc.
https://github.com/janosh/matterviz
chemistry d3 data-viz materials-science plotting svelte threejs
Last synced: about 1 month ago
JSON representation
Interactive browser visualizations for materials science: crystal structures/molecules, trajectories, convex hulls, phase diagrams, Fermi surfaces, bands+DOS, Brillouin zones, etc.
- Host: GitHub
- URL: https://github.com/janosh/matterviz
- Owner: janosh
- License: mit
- Created: 2022-06-01T15:29:36.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2026-06-09T16:07:27.000Z (about 1 month ago)
- Last Synced: 2026-06-09T18:06:46.169Z (about 1 month ago)
- Topics: chemistry, d3, data-viz, materials-science, plotting, svelte, threejs
- Language: TypeScript
- Homepage: https://janosh.github.io/matterviz
- Size: 45.9 MB
- Stars: 342
- Watchers: 4
- Forks: 34
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- Contributing: contributing.md
- License: license
- Citation: citation.cff
Awesome Lists containing this project
- best-of-atomistic-machine-learning - GitHub - 11% open · ⏱️ 06.11.2025): (Visualization)
- awesome-sveltekit - [code
README
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
import { PeriodicTable } from 'matterviz'
const heatmap_values = { H: 10, He: 4, Li: 8, Fe: 3, O: 24 }
```
### Structure
```svelte
import { Structure } from 'matterviz'
const data_url = '/structures/TiO2.cif'
// supports .cif, .poscar, .xyz/.extxyz, pymatgen JSON, OPTIMADE JSON, .gz
```
### Composition
```svelte
import { Composition } from 'matterviz'
// modes can be 'pie' (default) | 'bubble' | 'bar'
```
### Trajectory
```svelte
import { Trajectory } from 'matterviz'
// supports .xyz/.extxyz, .traj, .hdf5, .npz, .pkl, .dat, .gz, .zip, .bz2, .xz
```
## 🧪 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
}
```