Nitro Bio Sequence Viewers

React components for DNA, RNA, and protein sequences: residue-level comparison, linear and circular annotation maps, selection, FASTA export, and optional browser alignment. MIT licensed. Supports React 18.2+ and React 19, with compiled CSS and no Tailwind requirement.

Interactive documentation · Plain Markdown · Usage guide · Workloads and accessibility

Start here

npm install @nitro-bio/sequence-viewers

"use client";

import { SequenceViewer } from "@nitro-bio/sequence-viewers";
import "@nitro-bio/sequence-viewers/styles.css";

export default function SequenceExample() {
  return <SequenceViewer sequences={["ATGACCTG", "ATGTCCTG"]} />;
}

This is a complete component. Selection is managed internally and residues have default styling. To share selection with your application, pass selection and setSelection. To customize residue classes, pass charClassName.

In Next.js App Router, keep the viewer import in a client component; the stylesheet can live in the root layout. Complete, runnable examples are included:

• Next.js App Router with React 19
• Vite with React 18

Both examples are built and exercised against the packed npm artifact in CI.

Choose a viewer

| Component | Use it for | | ------------------------------------------------------- | ------------------------------------------------------------------------ | | SequenceViewer | Individual residues, annotations, selection, and comparing aligned rows. | | LinearViewer | A linear overview linked to residue selection. | | CircularViewer | Circular maps and regions that cross the origin. |

The residue viewer automatically windows large inputs while keeping full selection, copy, download, mismatch, and annotation behavior. Read the measurements and operating guidance for the exact threshold and remaining memory costs. Strings are rendered without biological alphabet validation; coordinate and validation contracts are in the usage guide.

Position labels

Pass positionLabels to label aligned columns with antibody insertion codes, PDB residue identifiers, or genomic coordinates. The packaged minimal renderer is the default; opt into the adaptive renderer for dense labels:

import {
  SequenceViewer,
  AdaptivePositionLabel,
} from "@nitro-bio/sequence-viewers";

<SequenceViewer
  sequences={["AC-GT", "ACTGT"]}
  positionLabels={["35", "35a", null, "36", "37"]}
  positionLabelRenderer={AdaptivePositionLabel}
/>;

Each label describes one displayed column; null leaves it blank. Labels change the ruler only: selection and annotation coordinates remain zero-based column indices. Omit both label props to retain the existing ruler. See the position-label guide for MinimalPositionLabel, AdaptivePositionLabel, and the custom React component slot.

Optional alignment

Alignment is off by default. Viewing does not download alignment tools. Enable it with enableAlignment and setSequences; the first Align action downloads MAFFT JavaScript/WebAssembly and computes locally in a browser worker.

Use the self-hosting recipe to prepare assets for your own server. The alignment reference covers asset versions, CSP/CORS settings, failure recovery, and worker limits.

Styling and compatibility

Import @nitro-bio/sequence-viewers/styles.css once. The package does not reset host styles. Customize --nsv-color-sequences-* tokens; caller-provided classes are preserved. The supported CSS browser floor is Safari 16.4+, Chrome 111+, and Firefox 128+. See the CSS guide for portal themes and migration from version 1.

Version 2.1 makes selection and styling props optional and fixes the annotation click callback's direction field. Existing controlled integrations remain supported. See usage and validation.

Used in

• NVIDIA Build
• Tatta Bio Gaia
• EvolutionaryScale Forge
• Nitro Bio Sequences

Development

Use pnpm 11.9.0 from the repository root:

pnpm install --frozen-lockfile
pnpm lint
pnpm format
pnpm test
pnpm build:ci
pnpm exec playwright install chromium
pnpm test:packed

Packed consumer checks cover React 18/19, plain CSS and Tailwind 3/4 integration, position labels and virtualized rulers, selection and copying, validation recovery, and real self-hosted MAFFT under CSP. pnpm dev starts Storybook. pnpm benchmark records production-browser workload measurements; see the benchmark guide for reproduction.

Publishing

The manual Publish to npm workflow publishes the version committed to main. It builds the package and runs the packed integration suite before publishing that same tarball to npm's latest tag.

A package maintainer must configure npm trusted publishing once, using npm 11.15 or newer and completing its two-factor authentication prompt:

npm trust github @nitro-bio/sequence-viewers --repo nitro-bio/sequence-viewers --file publish.yml --allow-publish

The equivalent npm package settings are GitHub owner nitro-bio, repository sequence-viewers, workflow filename publish.yml, no environment, and direct npm publish permission. The workflow uses GitHub's OIDC identity; no npm token secret or per-release npm login is needed.

For each release, apply the changeset and merge the version bump into main, then select Actions → Publish to npm → Run workflow, choose main, and enter the committed version. The workflow checks that the entered version matches package.json.

Report an issue with the package version, framework, browser, and a minimal reproducer.