Installation

Prerequisites

Before installing Annota, ensure you have:

• Node.js 18 or higher
• React 18+ / 19+ OR Svelte 5
• A package manager (npm, pnpm, or yarn)

Choose Your Framework

Annota provides identical functionality for both React and Svelte. The only difference is the reactive API (hooks vs stores).

React

React Installation

React users get:

• React hooks (useAnnotator, useAnnotations, useTool, etc.)
• React components with JSX
• Full TypeScript support
• Optimized for React 18+ and React 19+

Svelte

Svelte Installation

Svelte users get:

• Svelte stores (annotator(), annotations(), tool(), etc.)
• Svelte components with Svelte 5 runes
• Full TypeScript support
• Optimized for Svelte 5

Install Core Package

npm

npm install annota openseadragon

pnpm

pnpm add annota openseadragon

yarn

yarn add annota openseadragon

Note

OpenSeadragon is a required peer dependency for viewport management and image display.

TypeScript Support

Annota is written in TypeScript and includes full type definitions. For OpenSeadragon types:

npm

npm install --save-dev @types/openseadragon

pnpm

pnpm add -D @types/openseadragon

yarn

yarn add -D @types/openseadragon

Import Styles

Import the required CSS in your app entry point:

React:

import "annota/dist/index.css";

Svelte:

<script>
  import "annota/dist/index.css";
</script>

Or in your global CSS:

@import "annota/dist/index.css";

Verify Installation

React Verification

Create a simple test component:

import { AnnotaProvider, AnnotaViewer, Annotator } from "annota";
import { useState } from "react";
import "annota/dist/index.css";

function TestViewer() {
  const [viewer, setViewer] = useState(null);

  return (
    <AnnotaProvider>
      <div style={{ width: "800px", height: "600px" }}>
        <AnnotaViewer
          options={{
            tileSources: {
              type: "image",
              url: "https://picsum.photos/1920/1080",
            },
            prefixUrl: "https://cdn.jsdelivr.net/npm/openseadragon@4/build/openseadragon/images/",
          }}
          onViewerReady={setViewer}
        />
        <Annotator viewer={viewer} />
      </div>
    </AnnotaProvider>
  );
}

Svelte Verification

Create a simple test component:

<script>
  import { AnnotaProvider, AnnotaViewer, Annotator } from "annota/svelte";
  import "annota/dist/index.css";

  let viewer = $state(null);
</script>

<AnnotaProvider>
  <div style="width: 800px; height: 600px;">
    <AnnotaViewer
      options={{
        tileSources: {
          type: "image",
          url: "https://picsum.photos/1920/1080",
        },
        prefixUrl: "https://cdn.jsdelivr.net/npm/openseadragon@4/build/openseadragon/images/",
      }}
      onViewerReady={(v) => viewer = v}
    />

      <Annotator {viewer} />
    {/if}
  </div>
</AnnotaProvider>

If you see an image viewer in either case, Annota is installed correctly!

Optional Dependencies

H5 File Support

For loading HDF5 annotation files:

npm

npm install h5wasm

pnpm

pnpm add h5wasm

yarn

yarn add h5wasm

SAM Tool (AI-Assisted Segmentation)

For the Segment Anything Model tool, you’ll need ONNX Runtime:

npm

npm install onnxruntime-web

pnpm

pnpm add onnxruntime-web

yarn

yarn add onnxruntime-web

Next Steps

Now that Annota is installed, continue to:

• React Quick Start — Build your first React annotation viewer
• Svelte Quick Start — Build your first Svelte annotation viewer
• Core Concepts — Understand annotations, layers, and tools (framework-agnostic)
• Framework Comparison — Compare React and Svelte APIs