A lightweight, extensible React implementation of the **Nano Protein Viewer**, originally developed as a VSCode extension by [**Steven Yu**](https://marketplace.visualstudio.com/items?itemName=StevenYu.nano-protein-viewer).
npm install @juliocesar-io/nano-protein-viewer-react```
█▄░█ ▄▀█ █▄░█ █▀█ █▀█ █▀█ █▀█ ▀█▀ █▀▀ █ █▄░█ █▀█ █▀▀ ▄▀█ █▀▀ ▀█▀
█░▀█ █▀█ █░▀█ █▄█ █▀▀ █▀▄ █▄█ ░█░ ██▄ █ █░▀█ █▀▄ ██▄ █▀█ █▄▄ ░█░
!demo
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.
`bash`
pnpm install @juliocesar-io/nano-protein-viewer-react
Run tests
`bash`
pnpm test
`tsx
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 (
Local development
Run the example react_app locally:
`bash
cd react_app
pnpm install
pnpm dev
`Go to: http://localhost:5173
!grid
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
$3
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:
`ts
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 } }
}
];
`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}
}
``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