Svelte Stores

Svelte stores provide reactive access to Annota’s state. Unlike React hooks, Svelte stores are called as functions and return reactive values using Svelte 5 runes.

Overview

React vs Svelte

React Hooks → Svelte Stores

React Hook	Svelte Store	Notes
useAnnotator()	getAnnotator()()	Returns annotator (needs $derived)
useAnnotations()	annotations()	Returns reactive array
useSelection()	selection()	Returns reactive array
useTool()	tool()	Tool activation function
useHistory()	history()	Returns history object
useLayers()	layers()	Returns reactive array
useLayerManager()	layerManager()	Returns manager instance

Pattern

Usage Pattern

React Hooks:

const annotator = useAnnotator();
const annotations = useAnnotations();

Svelte Stores:

<script>
  const getAnnotatorFn = getAnnotator();
  const annotator = $derived(getAnnotatorFn());
  const allAnnotations = annotations();
</script>

Available Stores

annotations()

Get all annotations as a reactive getter function.

function annotations(): () => Annotation[];

Usage:

<script>
  import { annotations } from "annota/svelte";

  const getAnnotations = annotations();
  // Use $derived to make it reactive
  const allAnnotations = $derived(getAnnotations());
  const count = $derived(allAnnotations.length);
</script>

<p>Annotations: {count}</p>

selection()

Get currently selected annotations as a reactive getter function.

function selection(): () => Annotation[];

Usage:

<script>
  import { selection } from "annota/svelte";

  const getSelectedAnnotations = selection();
  // Use $derived to make it reactive
  const selectedAnnotations = $derived(getSelectedAnnotations());
  const hasSelection = $derived(selectedAnnotations.length > 0);
</script>

{#if hasSelection}
  <p>{selectedAnnotations.length} annotations selected</p>
{/if}

tool()

Activate annotation tools.

function tool(config: ToolConfig): void;

Usage:

<script>
  import { tool } from "annota/svelte";
  import { RectangleTool } from "annota";

  let viewer = $state(null);
  let activeTool = $state("rectangle");

  const rectTool = $derived(new RectangleTool());

  $effect(() => {
    if (!viewer) return;

    tool({
      viewer: () => viewer,
      handler: () => (activeTool === "rectangle" ? rectTool : null),
      enabled: () => activeTool === "rectangle",
    });
  });
</script>

getAnnotator()

Access the annotator instance.

function getAnnotator(): () => Annotator | undefined;

Usage:

<script>
  import { getAnnotator } from "annota/svelte";

  const getAnnotatorFn = getAnnotator();
  const annotator = $derived(getAnnotatorFn());

  function handleClear() {
    if ($annotator) {
      $annotator.clearAnnotations();
    }
  }
</script>

history()

Access undo/redo history.

function history(): {
  canUndo: boolean;
  canRedo: boolean;
  undoSize: number;
  redoSize: number;
  undo: () => void;
  redo: () => void;
};

Usage:

<script>
  import { history } from "annota/svelte";

  const historyInstance = history();
</script>

<button disabled={!historyInstance.canUndo} onclick={historyInstance.undo}>
  Undo
</button>
<button disabled={!historyInstance.canRedo} onclick={historyInstance.redo}>
  Redo
</button>

layers()

Get all layers.

function layers(): Layer[];

Usage:

<script>
  import { layers } from "annota/svelte";

  const allLayers = layers();
</script>

{#each allLayers as layer (layer.id)}
  <div>{layer.name}</div>
{/each}

layerManager()

Manage layers.

function layerManager(): LayerManager;

Usage:

<script>
  import { layerManager } from "annota/svelte";

  const manager = layerManager();

  function addLayer() {
    manager.addLayer({
      id: "layer-1",
      name: "New Layer",
      visible: true,
    });
  }
</script>

Advanced Patterns

Combining Multiple Stores

<script>
  import { annotations, selection, getAnnotator } from "annota/svelte";

  const getAnnotations = annotations();
  const getSelection = selection();
  const getAnnotatorFn = getAnnotator();

  const allAnnotations = $derived(getAnnotations());
  const selectedAnnotations = $derived(getSelection());
  const annotator = $derived(getAnnotatorFn());

  // Derived: Count selected vs total
  const selectionRatio = $derived(
    selectedAnnotations.length / allAnnotations.length
  );

  // Derived: Get selected annotation IDs
  const selectedIds = $derived(selectedAnnotations.map((a) => a.id));
</script>

Reactive Updates

<script>
  import { annotations } from "annota/svelte";

  const getAnnotations = annotations();
  const allAnnotations = $derived(getAnnotations());

  // Automatically updates when annotations change
  $effect(() => {
    console.log("Annotations count:", allAnnotations.length);
    // Save to local storage, etc.
  });
</script>

Tip

Svelte 5 Runes: Unlike React hooks, Svelte stores don’t need dependency arrays. The $effect automatically tracks reactive dependencies.

See Also

• React Hooks API - For comparison with React
• Core Concepts - Framework-agnostic concepts
• Annotator API - Programmatic API