File Upload

File Upload allows you to load documents into the canvas by providing a valid file URL or by passing a real browser File object from an input element. This process initializes the canvas tools and establishes the metadata state for the session.

By managing files through the communication bridge, you maintain total control over document access while leveraging the high-performance rendering engine.

• URL Loading: The file URL must be publicly accessible on the internet.
• Any File URL Loading: The viewAny message accepts fileUrl, displayName, cacheId, and mime.
• Display Name: Use the complete file name with extension, such as Sample.pdf or Apple Sample.pdf.
• Local Loading: The viewFile message requires a real browser File object, usually from an input[type="file"].
• Dynamic Loading: Open any supported document format on the fly.
• Session Lifecycle: Track the status of document processing from start to finish.
• Automated Initialization: Canvas tools auto-calibrate based on the loaded file type.

Send a view payload to load a file and listen for fileInfo to confirm readiness.

iframe.contentWindow.postMessage({
  type: 'view',
  payload: { fileUrl: 'https://example.com/document.pdf' }
}, viewerOrigin);

const file = document.querySelector('input[type="file"]').files[0];

iframe.contentWindow.postMessage({
  type: 'viewFile',
  payload: file
}, viewerOrigin);

iframe.contentWindow.postMessage({
  type: 'viewAny',
  payload: {
    fileUrl: 'https://example.com/sample.pdf',
    displayName: 'Sample.pdf',
    cacheId: 'sample-pdf-cache-id',
    mime: 'application/pdf'
  }
}, viewerOrigin);

window.addEventListener('message', (event) => {
  if (event.data.type === 'fileInfo') {
    console.log('Loaded:', event.data.payload.fileInfo.name)
  }
});

Loading a document follows a request-response pattern. You dispatch a view, viewAny, or viewFile message to start the rendering process, and the canvas provides status updates until the document is ready.

const iframe = document.querySelector('[data-viewer-iframe]');

iframe.contentWindow.postMessage({
  type: 'viewAny',
  payload: {
    fileUrl: 'https://example.com/sample.pdf',
    displayName: 'Apple Sample.pdf',
    cacheId: 'apple-sample-cache-id',
    mime: 'application/pdf'
  }
}, '*');

// 1. Get a handle to the canvas iframe (e.g. via ref or selector)
const iframe = document.querySelector('[data-viewer-iframe]');

// 2. Command the canvas to load a specific file URL
iframe.contentWindow.postMessage({
  type: 'view',
  payload: {
    fileUrl: 'https://example.com/document.pdf'
  }
}, '*');

const input = document.querySelector('input[type="file"]');
const file = input.files[0];
const iframe = document.querySelector('[data-viewer-iframe]');

if (file) {
  iframe.contentWindow.postMessage({
    type: 'viewFile',
    payload: file
  }, '*');
}

// Listen for "fileInfo" to retrieve document metadata
window.addEventListener('message', (event) => {
  if (event.data.type === 'fileInfo') {
    const { name, width, height } = event.data.payload.fileInfo;
    console.log(`Loaded ${name}: ${width}x${height}px`);
  }
});

The canvas emits specific events to help you manage UI loaders and progress indicators during document processing.

• progressStart: Emitted when the canvas begins downloading or parsing a file.
• progressEnd: Emitted when the processing is complete and the UI is interactive.

// example: managing a loading spinner
window.addEventListener('message', (event) => {
  if (event.data.type === 'progressStart') {
    setIsLoading(true);
  }
  if (event.data.type === 'progressEnd') {
    setIsLoading(false);
  }
});

Initialize the iframe, load a file from either a URL or a local file input, and handle progress and metadata events.

const VIEWER_URL = 'https://your-canvas-domain.com';
const VIEWER_ORIGIN = 'https://your-canvas-domain.com';

const iframe = document.querySelector('[data-viewer-iframe]');
const fileInput = document.querySelector('input[type="file"]');
iframe.src = VIEWER_URL;

iframe.addEventListener('load', () => {
  iframe.contentWindow.postMessage({
    type: 'view',
    payload: { fileUrl: 'https://example.com/document.pdf' }
  }, VIEWER_ORIGIN);
});

fileInput.addEventListener('change', () => {
  const file = fileInput.files[0];
  if (!file) return;
  iframe.contentWindow.postMessage({
    type: 'viewFile',
    payload: file
  }, VIEWER_ORIGIN);
});

window.addEventListener('message', (event) => {
  if (event.origin !== VIEWER_ORIGIN) return;
  if (event.data.type === 'progressStart') setIsLoading(true);
  if (event.data.type === 'progressEnd') setIsLoading(false);
  if (event.data.type === 'fileInfo') {
    console.log('Loaded:', event.data.payload.fileInfo.name);
  }
});

Test the interactive preview below to see how the session initializes when a new file is requested.

Continue with related file workflows and API references.

• Canvas Setup: Canvas Iframe Initialization
• File Management: File Management
• File API: API References