3Dmol.js

2.5.4 verified Sat May 09 auth: no javascript

3Dmol.js is a WebGL-powered JavaScript library for interactive molecular visualization in browsers. Current stable version is 2.5.4, released with improvements to aromatic bond visualization. Releases occur approximately every 2-4 months with incremental feature additions and bug fixes. Key differentiators include support for multiple molecular formats (PDB, SDF, MOL2, XYZ, CIF, MMTF, etc.), parallelized surface computation, rich styling (cartoon, stick, sphere, surface), and both hosted/embeddable viewer modes. It is licensed under BSD and widely cited in bioinformatics. Unlike alternatives (e.g., NGL Viewer, JSmol), 3Dmol.js offers seamless integration with JavaScript apps and a simpler API for quick molecular rendering.

Common errors

error TypeError: Cannot read properties of undefined (reading 'createViewer') ↓

cause Importing as named export 'createViewer' instead of default import.

fix

Use import $3Dmol from '3dmol' then $3Dmol.createViewer

error WebGL context lost error ↓

cause Multiple viewers or inappropriate antialiasing settings in older versions.

fix

Upgrade to >=2.4.1 or use a single viewer instance

error Error: PDB parsing error: unexpected token ↓

cause File path not resolved or CORS issue when loading local files.

fix

Ensure file is served over HTTP/HTTPS and correct path is provided

error Cannot find module '3dmol' ↓

cause Package not installed or installed in wrong location.

fix

Run npm install 3dmol or include script tag from CDN

Warnings

breaking In some older versions, Background transparency rendering can cause WebGL context loss with antialiasing. ↓

fix Upgrade to >=2.4.1 or set antialias: false

breaking Viewer grid bug on large canvases in some browsers. ↓

fix Upgrade to >=2.5.3

deprecated The use of require() with CommonJS may not work in all bundlers; ESM imports are recommended. ↓

fix Use import $3Dmol from '3dmol' instead of require

gotcha Antialiasing may not work as expected with very small or very large viewports. ↓

fix Adjust maxpixels or antialias settings; see documentation

gotcha Surface computation is async; ensure viewer.render() is called after surface added. ↓

fix Use callback in addSurface or call render after promise resolves

Install

npm install 3dmol

yarn add 3dmol

pnpm add 3dmol

Imports

$3Dmol
wrong
```
const $3Dmol = require('3dmol')
```
correct
```
import $3Dmol from '3dmol'
```
ESM default import for v2+. Node.js require works but is not guaranteed to be stable in all bundlers.

$3Dmol.createViewer

wrong

const { createViewer } = require('3dmol')

correct

import $3Dmol from '3dmol'; const viewer = $3Dmol.createViewer(element)

createViewer is a method on the default export, not a named export.

$3Dmol.download
wrong
```
const download = require('3dmol').download
```
correct
```
import $3Dmol from '3dmol'; $3Dmol.download('pdb:1XYZ', viewer, {}, callback)
```
Download is a method on the default export. Named import works in some bundlers but is not officially supported.

$3Dmol.SurfaceType

wrong

const { SurfaceType } = require('3dmol')

correct

import $3Dmol from '3dmol'; const surface = $3Dmol.SurfaceType.VDW

SurfaceType is a property of the default export, not a named export.

Quickstart

Creates a 3Dmol.js viewer, loads a PDB structure, applies cartoon style, adds a surface, and draws a cylinder.

import $3Dmol from '3dmol';

const viewer = $3Dmol.createViewer('viewer-div', {
    backgroundColor: 'white',
    antialias: true
});

$3Dmol.download('pdb:4N8T', viewer, {}, function() {
    viewer.setStyle({}, {cartoon: {color: 'spectrum'}});
    viewer.render();
});

viewer.addSurface($3Dmol.SurfaceType.VDW, {
    opacity: 0.85,
    voldata: new $3Dmol.VolumeData({}, 'cube'),
    volscheme: new $3Dmol.Gradient.ROYGB(-5, 5)
}, {});

viewer.addCylinder({
    start: {x: 0, y: 2, z: 0},
    end: {x: 0, y: 10, z: 0},
    radius: 0.5,
    color: 'teal'
});