Rasterex APINPM Package/docs/components/placement/symbols

Symbols

Control the canvas symbols panel from the host application using the SDK.

Overview

Use viewer.tools.symbols to open, close, or toggle the Canvas symbols panel.

Symbol tools are available after the viewer is mounted, Canvas is ready, and a document is open.

typescript

import { createViewer } from "@rasterex/viewer";

const viewer = createViewer({
  container: "#viewer"
});

await viewer.mount();
await viewer.ready();

await viewer.documents.open({
  url: "https://files.example.com/sample.pdf",
  displayName: "Sample PDF.pdf"
});

Overview

Open, Close or Toggle Panel

Toggle the visibility state of the symbols panel programmatically. These methods return a Promise resolving to the panel status:

viewer.tools.symbols.open() sends symbolsControl with command: "open" and waits for symbolsControlResult.
You can specify an optional custom timeout:

Toggle symbols panel with timeout

await viewer.tools.symbols.toggle({
  timeoutMs: 8000
});

typescript

// Open the symbols panel
await viewer.tools.symbols.open();

// Close the symbols panel
await viewer.tools.symbols.close();

// Toggle the symbols panel
await viewer.tools.symbols.toggle();

Open, Close or Toggle Panel

Result Shape

Symbol panel methods return the standard panel result shape:

The SDK rejects the Promise when the viewer is not ready, the Canvas message broker is unavailable, Canvas does not return a response before the timeout, or a Canvas-side failure occurs.

typescript

type StampPanelResult = {
  success: boolean;
  requestId?: string;
  command?: "open" | "close" | "toggle";
  opened?: boolean;
  error?: string;
};

Result Shape

Vanilla Example

Complete integration code setup for Vanilla HTML/JS environments:

<div id="viewer" style="height: 640px"></div>
<div>
  <button type="button" id="open-symbols">Open Symbols</button>
  <button type="button" id="close-symbols">Close Symbols</button>
  <button type="button" id="toggle-symbols">Toggle Symbols</button>
</div>
<p id="status"></p>

Vanilla Example

React Integration

Complete React Component implementation details:

tsx

import { useEffect, useRef, useState } from "react";
import { createViewer, type RasterexViewer } from "@rasterex/viewer";

export function SymbolTools() {
  const hostRef = useRef<HTMLDivElement | null>(null);
  const viewerRef = useRef<RasterexViewer | null>(null);
  const [status, setStatus] = useState("Loading viewer");

  useEffect(() => {
    let disposed = false;
    const viewer = createViewer({ container: hostRef.current! });
    viewerRef.current = viewer;

    async function start() {
      await viewer.mount();
      await viewer.ready();
      await viewer.documents.open({
        url: "https://files.example.com/sample.pdf",
        displayName: "Sample PDF.pdf"
      });
      if (!disposed) setStatus("Ready");
    }

    void start().catch((error) => {
      if (!disposed) setStatus(error instanceof Error ? error.message : "Viewer failed");
    });

    return () => {
      disposed = true;
      viewer.destroy();
      viewerRef.current = null;
    };
  }, []);

  async function openSymbols() {
    const result = await viewerRef.current?.tools.symbols.open();
    setStatus(result?.success ? "Symbols panel opened" : result?.error ?? "Open failed");
  }

  async function closeSymbols() {
    const result = await viewerRef.current?.tools.symbols.close();
    setStatus(result?.success ? "Symbols panel closed" : result?.error ?? "Close failed");
  }

  async function toggleSymbols() {
    const result = await viewerRef.current?.tools.symbols.toggle();
    setStatus(result?.success ? "Symbols panel toggled" : result?.error ?? "Toggle failed");
  }

  return (
    <section>
      <div ref={hostRef} style={{ height: 640 }} />
      <div>
        <button type="button" onClick={() => void openSymbols()}>Open Symbols</button>
        <button type="button" onClick={() => void closeSymbols()}>Close Symbols</button>
        <button type="button" onClick={() => void toggleSymbols()}>Toggle Symbols</button>
      </div>
      <p>{status}</p>
    </section>
  );
}

React Integration

Canvas Broker Mapping

Broker message mapping for symbol tools:

viewer.tools.symbols.open(...) maps to symbolsControl / symbolsControlResult.
viewer.tools.symbols.close(...) maps to symbolsControl / symbolsControlResult.
viewer.tools.symbols.toggle(...) maps to symbolsControl / symbolsControlResult.