Source: https://docs.nitro.bio/SequenceViewer

# 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](https://github.com/nitro-bio/sequence-viewers/blob/v2.1.0/src/components/Ariadne/SequenceViewer/SequenceViewer.tsx) · [Read as Markdown](https://docs.nitro.bio/SequenceViewer.md)

## Installation

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

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

```tsx
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:

```tsx
"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](https://github.com/nitro-bio/sequence-viewers/tree/v2.1.0/examples/next) or [Vite example](https://github.com/nitro-bio/sequence-viewers/tree/v2.1.0/examples/vite) 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](https://docs.nitro.bio/SequenceViewer#browser-alignment) 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:

```tsx
<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](https://github.com/nitro-bio/sequence-viewers/blob/v2.1.0/docs/alignment-self-hosting.md) 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](https://github.com/nitro-bio/sequence-viewers/blob/v2.1.0/docs/issue-80/alignment.md) 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.

```tsx
"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](https://docs.nitro.bio/LinearViewer) or [Circular Viewer](https://docs.nitro.bio/CircularViewer).

## Annotations

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

```tsx
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.

```css
.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](https://github.com/nitro-bio/sequence-viewers/blob/v2.1.0/docs/issue-80/css-isolation.md) 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](https://github.com/nitro-bio/sequence-viewers/blob/v2.1.0/docs/limits.md) before choosing it for long sequences or large alignments. The [reproducible benchmark](https://github.com/nitro-bio/sequence-viewers/tree/v2.1.0/benchmarks) 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

| Prop                                         | Purpose                                                               |
| -------------------------------------------- | --------------------------------------------------------------------- |
| `sequences: string[]`                        | Sequence rows to render.                                              |
| `selection?: AriadneSelection or null`       | Controlled selected range; omit for internal state.                   |
| `setSelection?`                              | Receives changes; the host updates a controlled selection.            |
| `charClassName?({ base, sequenceIdx })`      | Optional callback returning your residue CSS classes.                 |
| `setSequences?`                              | Receives updated sequences; also required to apply alignment results. |
| `annotations?`                               | Optional `Annotation[]`; omission and an empty array are supported.   |
| `containerClassName?`, `selectionClassName?` | Style the viewer and selected region.                                 |
| `highlightMisalignments?`                    | Highlight mismatching positions across rows.                          |
| `hideMetadataBar?`, `hideDownloadButton?`    | Hide the metadata bar or download action.                             |
| `enableAlignment?`, `alignmentConfig?`       | Opt into alignment and configure asset loading.                       |
| `validationMode?`                            | `"recover"` (default) or `"strict"`.                                  |

## 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.