Core API Reference

⚠️ Public API Scope InkLayer only guarantees stable public API for the following two components:

PdfAnnotator (React / Vue)

PdfViewer (React / Vue)

All Hooks, Composables, Store, Adapter, and internal utility functions are internal implementation details. They are not guaranteed to be cross-version compatible and are not recommended for direct use.

This page covers the complete Props reference for PdfAnnotator and PdfViewer, as well as the Annotation data model (the only format for persistence storage).

Top-Level Exports

// React — inklayer-react
export { PdfAnnotator, PdfViewer } from 'inklayer-react'
export type { PdfAnnotatorProps, PdfViewerProps, Annotation, User } from 'inklayer-react'

// Vue — inklayer-vue
export { PdfAnnotator, PdfViewer } from 'inklayer-vue'
export type { PdfAnnotatorProps, PdfViewerProps, Annotation, User } from 'inklayer-vue'

Note: inklayer-vue additionally exports PdfViewerProvider, which is an implementation detail of Vue’s composable API and is generally not needed for direct use.

PdfAnnotator Props

Prop	Type	Default	Description
`url`	`string \| ArrayBuffer \| Uint8Array`	Required	PDF document URL or data
`user`	`User`	Required	Current user info
`initialAnnotations`	`Annotation[]`	`[]`	Initial annotation data
`layoutStyle`	`React.CSSProperties` / `Vue.StyleValue`	React: `undefined` Vue: `{ width: '100vw', height: '100vh' }`	Container style
`defaultOptions`	`DefaultOptions`	see below	Default tool options
`theme`	`ThemeConfig`	see below	Theme configuration
`enableRange`	`boolean`	`false`	Whether to enable box-selection for multi-select
`defaultShowAnnotationsSidebar`	`boolean`	`false`	Whether to show the annotations sidebar by default
`title`	`string`	React: `undefined` Vue: `'PDF ANNOTATOR'`	Page title
`data` (React only)	`string`	`undefined`	Alias for `url`, lower priority
`onSave`	`(annotations: Annotation[]) => void`	—	Save callback
`onDocumentLoaded` (PdfViewer)	`(pdfDocument: PDFDocumentProxy) => void`	—	PDF document loaded
`onEventBusReady` (PdfViewer)	`(eventBus: EventBus) => void`	—	EventBus ready
`onAnnotationChanged`	`(annotations: Annotation[], type: 'add' \| 'update' \| 'delete') => void`	—	Annotation change callback
`onPageChanged`	`(pageIndex: number) => void`	—	Page change callback
`onZoomChanged`	`(scale: number) => void`	—	Zoom change callback
`onError`	`(error: Error) => void`	—	Error callback
`actions`	`React.ReactNode \| ((props: ActionsProps) => React.ReactNode)` / `Vue: #actions`	—	Custom actions area
`toolbar`	`React.ReactNode \| ((props: ToolbarProps) => React.ReactNode)` / `Vue: #toolbar`	—	Custom toolbar
`sidebar`	`React.ReactNode \| ((props: SidebarProps) => React.ReactNode)` / `Vue: #sidebar-search-sidebar` etc.	—	Custom sidebar

DefaultOptions

interface DefaultOptions {
  highlight?: {
    strokeColor?: string    // Default highlight color
    opacity?: number        // Default opacity
  }
  freetext?: {
    fontSize?: number       // Default font size
    fontFamily?: string     // Default font family
    strokeColor?: string    // Default text color
  }
  rectangle?: {
    strokeColor?: string    // Default border color
    fillColor?: string      // Default fill color
    strokeWidth?: number    // Default border width
  }
  circle?: {
    strokeColor?: string
    fillColor?: string
    strokeWidth?: number
  }
  signature?: {
    type?: 'Draw' | 'Enter' | 'Upload'  // Default signature method
    strokeColor?: string
    fontSize?: number
    fontFamily?: string
    maxSize?: number        // Max file size (bytes)
    defaultSignature?: string  // Default signature content
  }
  stamp?: {
    stamps?: Array<{ id: string; url: string; name: string }>  // Preset stamp list
  }
}

ThemeConfig

interface ThemeConfig {
  token?: {
    colorPrimary?: string       // Primary color
    colorSuccess?: string      // Success color
    colorWarning?: string       // Warning color
    colorError?: string         // Error color
    fontSize?: number           // Base font size
    borderRadius?: number       // Border radius
  }
  components?: {
    Button?: object
    Input?: object
    // Supports most antd / varlet component token overrides
  }
}

PdfViewer Props

PdfViewer is a read-only PDF viewer that does not support annotation editing. Other Props are consistent with PdfAnnotator (excluding annotation-related callbacks).

Prop	Type	Default	Description
`url`	`string \| ArrayBuffer \| Uint8Array`	Required	PDF document URL or data
`user`	`User`	—	User info (optional for read-only scenes)
`initialPage`	`number`	`0`	Initial page index
`initialScale`	`number \| 'auto'`	`'auto'`	Initial zoom, `'auto'` = fit width
`layoutStyle`	`React.CSSProperties` / `Vue.StyleValue`	Same as PdfAnnotator	Container style
`onDocumentLoaded`	`(pdfDocument: PDFDocumentProxy) => void`	—	PDF document loaded
`onEventBusReady`	`(eventBus: EventBus) => void`	—	EventBus ready
`onPageChanged`	`(pageIndex: number) => void`	—	Page change callback
`onZoomChanged`	`(scale: number) => void`	—	Zoom change callback
`onError`	`(error: Error) => void`	—	Error callback

ActionsProps Interface

When actions is passed as a function, it receives the following parameters:

interface ActionsProps {
  save: () => void                              // Trigger save
  getAnnotations: () => Annotation[]             // Get current annotations
  exportToExcel: () => void                     // Export to Excel (Vue only)
  exportToPdf: () => void                       // Export to PDF
}

PdfViewerContextValue Interface (React)

Access via PdfViewerContext:

interface PdfViewerContextValue {
  pageIndex: number              // Current page index
  scale: number                  // Current zoom scale
  pdfDocument: PDFDocumentProxy | null  // PDF document instance
  goToPage: (pageIndex: number) => void
  zoomTo: (scale: number | 'auto') => void
  getAnnotations: () => Annotation[]
  save: () => void
}

SidebarPanel Type (React)

type SidebarPanel = 'search' | 'annotations' | 'outline' | 'thumbnails'

Annotation Data Model

See Annotation System for details. Key points:

interface Annotation {
  id: string                  // Globally unique UUID
  kind: AnnotationKind        // Semantic classification
  target: AnnotationTarget   // Anchor info (geometry + pageIndex + coordinateSystem)
  payload?: AnnotationPayload // Semantic content
  appearance?: AnnotationAppearance  // Visual properties
  relations?: AnnotationRelations     // Relationships
  meta?: AnnotationMeta             // Metadata
}

Persistence tip: The onSave callback gives you the complete Annotation[] directly — you can send this array to your backend as-is. No internal storage utility functions are needed.