Sequence Viewer

Explore sequences one residue at a time, select regions, add annotations, and compare aligned rows. This page uses @nitro-bio/sequence-viewers 2.1.0, compatible with React 18.2+ and React 19.

View source · Read as Markdown

Installation

pnpm add @nitro-bio/sequence-viewers@^2.1.0

Import the public stylesheet once from your application entry point or Next.js root layout:

import "@nitro-bio/sequence-viewers/styles.css";

The stylesheet contains the component styles and does not reset your host page. Tailwind is optional. The supported browser floor is Safari 16.4, Chrome 111, and Firefox 128.

Quick start

This complete client component uses internal selection and default styling:

"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"]} />;
}

Use the complete Next.js App Router example or Vite example for a runnable application. Both are built and tested against the packed npm artifact. The Next.js example places the viewer in a client component and imports the CSS in the root layout.

Example

Drag across either row or click the coding-region annotation. These rows differ by one base. To see how gaps bring shifted sequences into alignment, try the alignment demo below.

Browser alignment

These synthetic DNA sequences share a common backbone. The second sequence adds GGA, and the third is missing four bases. Before alignment, the remaining bases appear shifted. Click Align to insert gaps (-) and bring the matching regions into the same columns. Reset alignment restores the original inputs so you can compare the result.

Alignment is disabled by default in the package; this demo enables it from the start. Pass enableAlignment and use setSequences to apply the result:

<SequenceViewer
  sequences={sequences}
  setSequences={(alignedSequences) => {
    setSequences(alignedSequences);
    setSelection(null);
  }}
  selection={selection}
  setSelection={setSelection}
  enableAlignment
  alignmentConfig={{ debug: false }}
/>

Alignment changes column coordinates. A successful alignment clears selection owned internally by the viewer. Controlled applications must clear or remap their selection in setSequences, as this demo does, and every application must clear or remap annotations whose coordinates changed.

The first Align action lazily loads MAFFT 7.520 and supporting assets from https://biowasm.com/cdn/v3. Sequence alignment runs in a browser worker; sequence input is not uploaded to an alignment service. An enabled viewer without setSequences shows a disabled alignment action.

Use the self-hosting setup command and complete recipe to prepare the assets in your application. alignmentConfig.urlCDN chooses your asset server. Set the configuration before the first alignment; remount the viewer to change an initialized worker's configuration. The alignment guide lists the required assets, CSP/CORS setup, and retry behavior.

Controlled selection

Omit selection to use the viewer's internal state. An optional setSelection callback observes changes. Pass both props to control selection from your application. Explicit selection={null} is a controlled empty selection. charClassName is optional and has default residue styling.

"use client";

import { useState } from "react";
import {
  SequenceViewer,
  type AriadneSelection,
} from "@nitro-bio/sequence-viewers";

export function SequenceExample() {
  const [sequences, setSequences] = useState([
    "ATGCGTACGTTAGCTAGCTA",
    "ATGCGTACGTTAGCTTGCTA",
  ]);
  const [selection, setSelection] = useState<AriadneSelection | null>(null);

  return (
    <SequenceViewer
      sequences={sequences}
      setSequences={setSequences}
      selection={selection}
      setSelection={setSelection}
      highlightMisalignments
    />
  );
}

selection is either null or { start, end, direction }. Coordinates are zero-based and selection highlighting includes both endpoints. A range whose start is greater than end crosses the origin. Share the same complete sequences and selection state when linking this component with a Linear Viewer or Circular Viewer.

Annotations

Annotations are optional. Each annotation describes a region and can provide a click handler and a CSS class from your application:

import type { Annotation } from "@nitro-bio/sequence-viewers";

const annotations: Annotation[] = [
  {
    text: "Coding region",
    type: "CDS",
    direction: "forward",
    start: 6,
    end: 18,
    className: "coding-region",
  },
];

Pass this array with annotations={annotations}. For a controlled viewer, set onClick: setSelection on an annotation to select it when clicked. The callback receives the annotation, including its zero-based start, inclusive end, and direction. Version 2.1 fixes the misspelled diection field emitted by version 2.0.

Styling

Pass your own class through containerClassName and override the public theme tokens. Mirror foreground and background tokens on .nsv-portal for the sequence menu, which renders outside the viewer root.

.my-sequence-viewer {
  --nsv-color-sequences-primary: #047857;
  --nsv-color-sequences-secondary: #4f46e5;
  --nsv-color-sequences-selection: #059669;
  --nsv-color-sequences-foreground: #18181b;
  --nsv-color-sequences-background: #fafafa;
  --nsv-color-sequences-mismatch: #ef4444;
  --nsv-color-sequences-gap: #9ca3af;
}
.nsv-portal {
  --nsv-color-sequences-foreground: #18181b;
  --nsv-color-sequences-background: #fafafa;
}
.coding-region {
  background: #047857;
  color: white;
}

Caller-provided classes are preserved. Define them in plain CSS, or compile them with your own Tailwind setup. You no longer need to scan the package's JavaScript with @source. See the CSS guide for details.

Validation

All three viewers use validationMode="recover" by default. Invalid annotations are omitted with a local diagnostic; unsafe sequence shapes show a local placeholder. Valid residues, case, and coordinates are preserved. This is structural validation, not biological alphabet validation.

Use validationMode="strict" to throw a ViewerValidationError for an application error boundary. Empty sequences render an empty state with no active copy, download, or alignment actions.

Workloads and accessibility

The residue viewer renders every displayed column and row; it does not virtualize the DOM. A 100 kb sequence or many sequence rows can create a large amount of browser work. Review the measured workloads and operating guidance before choosing it for long sequences or large alignments. The reproducible benchmark records mount and selection times against the packed library.

Residue and annotation selection currently use mouse interactions. Metadata controls have accessible names, but the sequence surface is not a complete keyboard or screen-reader editing interface. For keyboard access to a selected range, provide labeled start/end inputs and connect them through controlled selection. See the workload guide for the tested scope and limitations.

API reference

Upgrading from version 1

1. Import @nitro-bio/sequence-viewers/styles.css and remove package @source scanning.
2. Move viewer theme overrides to --nsv-color-sequences-*. Host Tailwind color variables no longer control the library defaults.
3. Add enableAlignment if you want the alignment action; setSequences alone no longer enables it.
4. Replace deprecated noValidate with validationMode. Legacy true maps to "recover", and explicit false maps to "strict"; an explicit mode takes precedence.

Existing dist/nitro.css and dist/nitro-sequence-viewers.css imports remain aliases for compatibility. The public styles.css entry is recommended for new code.