CifVis - Crystal Structure Visualisation

A JavaScript library and web component for visualising crystal structures from CIF files, powered by Three.js. Atoms, bonds and hydrogen bonds are displayed as entered in the CIF. Everything — CIF parsing, structure construction, and display — runs locally in the browser; there is no server component.

• Try it: interactive viewer — load your own CIF.
• Add it to your site: interactive widget walkthrough.

• Interactive 3D visualisation of crystal structures
• Anisotropic displacement parameters (ADPs), bonds, and hydrogen bonds
• Disorder group handling and crystal symmetry growing
• Difference- and deformation-density maps and contour sections
• Gaussian Cube overlays
• Coupled comparison viewers
• Collision-free atom labels
• Touch and mouse controls
• Self-contained web component

The full documentation site is the source of truth for everything below. It is a VitePress site under docs/; run npm run docs:dev to serve it locally.

• General — what CifVis is and the shared concepts (CIF model, structure model, Filters, density theory).
• Widget — the <cifview-widget> component: attributes, loading data, display modes, density, styling.
• JS Library — parsing CIFs, driving CrystalViewer, density maps, Filters, coupled viewers, Three.js integration.
• Atom Labels — activating labels and how placement works.
• Options Reference — the full options schema shared by CrystalViewer and the widget.
• Gallery — live examples with widget and library code.
• Developing CifVis — source layout and how the layers fit together.

For the generated API reference (every exported class/method), run npm run docs to build it at jsdoc-out/index.html.

npm install cifvis

<cifview-widget src="structure.cif" caption="Crystal Structure"></cifview-widget>

<script type="module">
  import { CifViewWidget } from 'cifvis';
</script>

See the widget docs for attributes, options, and styling.

<div id="viewer"></div>
<script type="module">
  import { CrystalViewer } from 'cifvis';

  const viewer = new CrystalViewer(document.getElementById('viewer'));
  await viewer.loadCIF(cifContent);
</script>

The package also exports CIF, CrystalStructure, ORTEP3JsStructure, formatValueEsd, and coupleViewerInteractions. See the library docs for the full API, density maps, and coupled viewers.

npm install       # install dependencies
npm run dev       # start development server
npm test          # run unit tests
npm run build     # build for production
npm run deploy    # build and publish the GitHub Pages deployment

Additional benchmark and integration-test scripts are documented in the contributing guide.

Chrome, Firefox, Safari, and Edge (latest). WebGL is required.

Licensed under the Mozilla Public License Version 2.0 — see LICENSE.

If you use this software in academic work, please cite it like this until a proper publication is available:

@software{cifvis,
  author = {Paul Niklas Ruth},
  title = {CifVis: A JavaScript Library for Crystal Structure Visualisation},
  year = {2025},
  url = {https://github.com/niolon/cifvis}
}