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

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








!demo




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

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

Run tests

`bash
pnpm test
`

Use in your app

`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}
}
``

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