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

# Circular Viewer

Render circular sequences and annotated features, including regions that cross the origin. This page uses `@nitro-bio/sequence-viewers` **2.2.0**.

[View source](https://github.com/nitro-bio/sequence-viewers/blob/v2.2.0/src/components/Ariadne/CircularViewer/CircularViewer.tsx) · [Read as Markdown](https://docs.nitro.bio/CircularViewer.md)

## Installation

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

Import `@nitro-bio/sequence-viewers/styles.css` once in your application entry point. React 18.2+ and React 19 are supported; Tailwind is optional.

## Compact example

```tsx
"use client";

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

export function CircularExample() {
  const [selection, setSelection] = useState<AriadneSelection | null>(null);
  return (
    <CircularViewer
      sequence={"ATGCA".repeat(10)}
      selection={selection}
      setSelection={setSelection}
      svgSizePX={320}
    />
  );
}
```

## Origin-spanning regions

A selection or annotation with `start > end` crosses the origin. Coordinates are zero-based, and selection highlighting includes both endpoints. This example selects from index 240 through the origin to index 30 in a 300-base sequence.

Pass the same sequence into a residue-level viewer as `sequences={[sequence]}` and share selection state. Keep the complete sequence in both components so circular ranges retain their coordinates.

## Annotations

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

const annotations: Annotation[] = [
  {
    text: "Origin-spanning feature",
    type: "CDS",
    direction: "forward",
    start: 240,
    end: 30,
    className: "circular-feature",
  },
];
```

Pass `annotations={annotations}` and define the class in your application:

```css
.circular-feature {
  fill: #047857;
  color: #047857;
}
```

Use the shared [theme tokens](https://docs.nitro.bio/SequenceViewer#styling) through `containerClassName` to match your application.

## API reference

| Prop                                  | Purpose                                                         |
| ------------------------------------- | --------------------------------------------------------------- |
| `sequence: string`                    | A complete circular sequence.                                   |
| `selection: AriadneSelection or null` | Controlled selected region.                                     |
| `setSelection`                        | Receives a selected range.                                      |
| `annotations?`                        | Optional annotated regions, including origin-spanning features. |
| `containerClassName?`                 | Viewer class for layout and theme tokens.                       |
| `svgSizePX?`, `svgPadding?`           | Set the diagram size and padding.                               |
| `validationMode?`                     | `"recover"` (default) or `"strict"`.                            |

Use recovery mode to display local diagnostics for malformed input, or strict mode with an error boundary. See the [version 2 migration notes](https://docs.nitro.bio/SequenceViewer#upgrading-from-version-1) for the deprecated `noValidate` mapping and updated stylesheet setup.