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

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