FAQ

Frequently asked questions about using InkLayer. If you can’t find an answer, feel free to ask on

inklayer-react GitHub Issues

inklayer-vue GitHub Issues

Installation & Setup

Q: The component renders but the page is blank — nothing is visible?

A: Troubleshoot in this order:

Check CSS import: Confirm import 'inklayer-react/style' (React) or import 'inklayer-vue/style' (Vue) is present
Check layoutStyle height: PdfAnnotator uses absolute positioning internally and needs an explicit height. Add layoutStyle={{ width: '100%', height: '600px' }} (React) or :layout-style="{ width: '100%', height: '600px' }" (Vue)
Open the browser console: Check for JavaScript errors
Verify PDF URL: Open the PDF URL directly in your browser to confirm it’s accessible (no CORS issues)
Use React/Vue DevTools: Inspect the PdfAnnotator DOM element to confirm it has a computed height

Q: Styles are missing after installation / component has no styles?

A: Make sure you’ve imported the corresponding style file:

React: import 'inklayer-react/style'
Vue: import 'inklayer-vue/style'

Q: Why is PDF loading slow?

A: Possible causes and solutions:

PDF file too large: Consider server-side chunked loading or pre-compression
Network latency: Deploy PDF files on a CDN or static asset server
Worker not loaded: PDF.js uses Web Workers for rendering — ensure the worker file is accessible

Q: Which PDF versions are supported?

A: InkLayer is built on PDF.js 4.3 and supports all PDF versions from 1.0 to 2.0, including encrypted PDFs (password required).

Annotations

Q: What annotation types are supported?

A: InkLayer supports 14 annotation types, including: highlight, strikeout, underline, free text, rectangle, circle, freehand, free highlight, signature, stamp, note, arrow, cloud, and selection. See the Annotation System docs.

Q: How do I save annotation data?

A: Get the Annotation[] array via the onSave (React) or @save (Vue) event, then send it to your backend:

// React
<PdfAnnotator
  onSave={(annotations) => {
    fetch('/api/save', {
      method: 'POST',
      body: JSON.stringify(annotations),
    })
  }}
/>

// Vue
<PdfAnnotator
  @save="(annotations) => saveToServer(annotations)"
/>

Q: How do I restore previously saved annotations?

A: Use the initialAnnotations prop to pass in previously saved annotation data. See the React or Vue docs for complete examples.

Q: Why don’t annotations display after passing `initialAnnotations`?

A: Check the following:

Is pageIndex 0-based? (First page is 0, not 1)
Is target.coordinateSystem set to 'pdf'? (not 'canvas')
Annotations only render after PDF loading completes (after onLoad fires)
Ensure initialAnnotations is an array: Annotation[], not a single object

Q: Can annotation data be exported to PDF?

A: Yes. InkLayer uses pdf-lib to embed annotations directly into PDF files, which can be viewed in any standard PDF reader.

Q: Can annotation data be exported to Excel?

A: Yes. The Vue version provides the exportToExcel() function to export annotation lists as Excel spreadsheets, ideal for review and archiving.

Customization & Extension

React: Use the actions prop to add custom buttons, or children for full replacement.
Vue: Use the toolbar and actions slots.

See the Architecture docs — Custom Extensions.

Q: How do I add custom annotation types?

A: Register a custom Adapter via AdapterRegistry to map your defined annotation data model to Konva rendering nodes. See the Core API Reference.

Q: Are the React and Vue APIs identical?

A: Both versions share the same Core layer (Annotation data model, Adapter, Integration), so annotation data structures are fully identical. Differences are only in framework bindings:

Props naming: React uses camelCase, Vue uses kebab-case (or camelCase with : binding)
Events: React uses onXxx, Vue uses @xxx
Custom UI: React uses Render Props, Vue uses Slots

Performance

Q: How do I handle large PDF files (100+ pages)?

By default InkLayer renders all pages. For very large PDFs, consider on-demand loading
Use PdfViewer instead of PdfAnnotator to reduce toolbar and sidebar overhead
Consider virtual scrolling to only render pages in the visible viewport

Q: Why does it lag with many annotations (1000+)?

Konva creates an independent Shape node per annotation — large node counts affect performance
Cache annotations per page and only render annotations for the currently visible page
Use Konva.Layer.batchDraw() to reduce repaint frequency

Q: How does it perform on mobile?

A: InkLayer works on mobile, with these caveats:

Canvas operations are performance-limited on mobile — reduce simultaneous annotation count
Use usePinchZoom() Hook for pinch-to-zoom gestures
Toolbar auto-collapses on small screens — UI is already adapted

Compatibility

Q: Which browsers are supported?

Browser	Minimum Version
Chrome	90+
Firefox	90+
Safari	15+
Edge	90+

Q: Is server-side rendering (SSR) supported?

A: InkLayer depends on the Canvas API and PDF.js (Web Workers) and does not support SSR. When using Next.js or Nuxt, dynamically import in client components:

// React — Next.js
import dynamic from 'next/dynamic'

const PdfAnnotator = dynamic(
  () => import('inklayer-react').then(m => m.PdfAnnotator),
  { ssr: false }
)

// Vue — Nuxt 3
// Wrap component in <ClientOnly>
<ClientOnly>
  <PdfAnnotator url="/doc.pdf" />
</ClientOnly>

Q: How do I handle other SSR frameworks (Astro, Remix, SvelteKit)?

A: Generic solution: ensure InkLayer components are only rendered on the client side, avoiding Canvas and PDF.js code execution during SSR. Framework-specific approaches:

Astro: Use client:load directive: <PdfAnnotator client:load />
Remix: Dynamically import in useEffect, or wrap with <ClientOnly>
SvelteKit: Use onMount() for dynamic imports, or Svelte’s client-only component mechanism

Internationalization

Q: How do I switch languages?

A: Set the locale prop:

locale="zh-CN" — Chinese (default)
locale="en-US" — English

Q: Which languages are supported?

A: Currently Chinese (Simplified) and English. Contributions for more translations are welcome.

License & Support

Q: Is InkLayer free?

A: Yes, InkLayer is licensed under MIT and can be freely used for both personal and commercial projects.

Q: How do I get help?

inklayer-react — React package repository
inklayer-vue — Vue package repository

FAQ