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:

1. Check CSS import: Confirm import 'inklayer-react/style' (React) or import 'inklayer-vue/style' (Vue) is present
2. 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)
3. Open the browser console: Check for JavaScript errors
4. Verify PDF URL: Open the PDF URL directly in your browser to confirm it’s accessible (no CORS issues)
5. 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:

1. Is pageIndex 0-based? (First page is 0, not 1)
2. Is target.coordinateSystem set to 'pdf'? (not 'canvas')
3. Annotations only render after PDF loading completes (after onLoad fires)
4. 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

Q: How do I customize the toolbar?

A:

• 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)?

A:

• 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+)?

A:

• 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?

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. The core InkLayer SDK is licensed under MIT and can be used free of charge in personal and commercial projects.

Q: How do I get help?

Community support:

• GitHub Discussions (React) / GitHub Discussions (Vue) — Ask questions, request features, share your use case
• GitHub Issues (React) / GitHub Issues (Vue) — Report bugs
• Documentation and Starter projects — Installation guidance, examples, and common integration questions

Community support is provided on a best-effort basis as maintainer time allows, without a guaranteed response time.

Commercial technical support:

Contact the maintainer if your project needs:

• React or Vue integration and troubleshooting
• Annotation persistence and backend integration
• User, role, and workflow permission integration
• Custom features or support for another framework
• Ongoing maintenance and priority response for a private project

Email: [email protected]

Please include your use case, technology stack, required capabilities, and target timeline.