█▄░█ ▄▀█ █▄░█ █▀█   █▀█ █▀█ █▀█ ▀█▀ █▀▀ █ █▄░█   █▀█ █▀▀ ▄▀█ █▀▀ ▀█▀
█░▀█ █▀█ █░▀█ █▄█   █▀▀ █▀▄ █▄█ ░█░ ██▄ █ █░▀█   █▀▄ ██▄ █▀█ █▄▄ ░█░

Overview

A lightweight, extensible React implementation of the Nano Protein Viewer, originally developed as a VSCode extension by Steven Yu.

This project brings the Mol*-powered molecular visualization experience to the web enabling integration into any React or Next.js application.

Install

pnpm install @juliocesar-io/nano-protein-viewer-react

Run tests

pnpm test

Use in your app

import { NanoProteinViewer, type StructureUrl } from '@juliocesar-io/nano-protein-viewer-react';

const structures: StructureUrl[] = [
  { name: '1CRN', url: 'https://files.rcsb.org/download/1CRN.pdb', format: 'pdb' }
];

export default function App() {
  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <NanoProteinViewer structureUrls={structures} />
    </div>
  );

Local development

Run the example react_app locally:

cd react_app
pnpm install
pnpm dev

Go to: http://localhost:5173

Design Rationale

This React app:

• Decouples the viewer logic into reusable components
• Enables embedding in research dashboards, notebooks, or web portals
• Provides a base to extend features (grid view, color themes, External API integration) gradually
• Allows server-side frameworks (Next.js, Remix, Vite) to integrate molecular viewers easily

Viewer Props

The viewer accepts an array of StructureUrl via the structureUrls prop. Each entry can optionally include initial style settings applied on load.

| Field | Type | Required | Description | | --------------------------- | ------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------- | | name | string | Yes | Display name for the structure. Also used for per-file settings. | | url | string | Yes | Direct URL to the structure file. | | format | StructureFormat ('pdb' \| 'mmcif' \| 'sdf') | No | Optional; auto-detected from name or url extension when omitted. | | style.colorMode | 'none' \| 'custom' \| 'element' \| 'residue' \| 'secondary' \| 'chain' \| 'rainbow' | No | Initial color theme applied on load. Use style.customColor when "custom". | | style.customColor | string (hex) | No | Used when colorMode is "custom". | | style.illustrative | boolean | No | Enables illustrative/cartoon effect. | | style.surface.enabled | boolean | No | Toggles molecular surface rendering. | | style.surface.opacity | number (0–100) | No | Surface opacity percentage. | | style.surface.inherit | boolean | No | Inherit surface color from current theme. | | style.surface.customColor | string (hex) | No | Surface color when not inheriting. |

Minimal example:

import { NanoProteinViewer, type StructureUrl } from '@juliocesar-io/nano-protein-viewer-react';

const structures: StructureUrl[] = [
  {
    name: 'AF-A0A2K6V5L6-F1',
    url: 'https://alphafold.ebi.ac.uk/files/AF-A0A2K6V5L6-F1-model_v6.cif',
    format: 'mmcif',
    style: { illustrative: true, surface: { enabled: true, opacity: 8, inherit: true } }
  },
  {
    name: '1CRN',
    url: 'https://files.rcsb.org/download/1CRN.pdb',
    format: 'pdb',
    style: { colorMode: 'secondary', customColor: '#4ECDC4', surface: { enabled: true, opacity: 40, inherit: true } }
  }
];

<NanoProteinViewer structureUrls={structures} />

License & Attribution

This project is released under the MIT License.

Adapted and inspired by the Nano Protein Viewer VSCode Extension by Steven Yu.

Mol* framework © Mol* team – see citation below.

Citation

If you use this viewer or the underlying Mol* visualization engine in academic work:

@article{sehnal2021molstar,
  author = {Sehnal, David and Bittrich, Sebastian and Deshpande, Mandar and Svobodová, Radka and Berka, Karel and Bazgier, Václav and Velankar, Sameer and Burley, Stephen K and Koča, Jaroslav and Rose, Alexander S},
  title = "{Mol* Viewer: modern web app for 3D visualization and analysis of large biomolecular structures}",
  journal = {Nucleic Acids Research},
  volume = {49},
  number = {W1},
  pages = {W431-W437},
  year = {2021},
  doi = {10.1093/nar/gkab314}
}

Contributing

Contributions are welcome! If you’ve added a visualization mode, folding integration, or UI control, please open a PR.

The roadmap includes:

• APIs integration for folding
• Structure alignment
• Animation playback
• Alphafold DB/ RCSB PDB search import