Skip to main content
Version: Beta

Document Viewer Widget

The Document Viewer widget displays a specific document by its ID. This widget is commonly used in combination with other widgets that support document interactions to create a comprehensive document browsing experience.

Table of Contents​

Basic Usage​

ES6 Modules​

import {AlphaSenseWidget} from '@alphasense/embedded-widgets'

const documentViewer = new AlphaSenseWidget({
  target: '#document-viewer',
  widgetType: 'documentViewer',
  documentViewerParams: {
    docId: 'your-document-id',
  },
  width: '100%',
  height: '600px',
}).init()

CDN Usage​

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document Viewer Example</title>
  </head>
  <body>
    <div id="document-viewer" style="width: 100%; height: 600px;"></div>

    <script src="https://unpkg.com/@alphasense/embedded-widgets@latest/dist/index.min.js"></script>
    <script>
      new AlphaSenseWidget({
        target: '#document-viewer',
        widgetType: 'documentViewer',
        documentViewerParams: {
          docId: 'your-document-id',
        },
        width: '100%',
        height: '600px',
      }).init()
    </script>
  </body>
</html>

Integration Patterns​

The Document Viewer works with any widget that supports the onDocumentClick callback to display selected documents.

For complete implementation examples including:

  • Citation handling with Generative Search
  • Side-by-side layouts and research interfaces
  • Modal/popup document viewing
  • Memory management and error handling
  • Responsive design patterns

See the comprehensive Widget Integration Patterns guide.

Configuration Options​

Required Parameters​

ParameterTypeDescription
targetstring | HTMLElementContainer element selector or HTMLElement
widgetTypestringMust be 'documentViewer'
documentViewerParams.docIdstringThe document ID to display

Optional Parameters​

ParameterTypeDefaultDescription
widthstring'100%'Widget width (CSS units)
heightstring'100%'Widget height (CSS units)
widgetUrlstringAuto-detectedCustom widget backend URL

Advanced Configuration​

const documentViewer = new AlphaSenseWidget({
  target: document.getElementById('my-viewer'), // HTMLElement instead of selector
  widgetType: 'documentViewer',
  documentViewerParams: {
    docId: 'document-123',
  },
  width: '800px',
  height: '600px',
}).init()

Error Handling​

Validation Errors​

The Document Viewer widget requires a valid docId. Handle validation errors appropriately:

try {
  const documentViewer = new AlphaSenseWidget({
    target: '#document-viewer',
    widgetType: 'documentViewer',
    documentViewerParams: {
      docId: '', // Invalid: empty docId
    },
  }).init()
} catch (error) {
  console.error('Document Viewer initialization failed:', error.message)

  // Show fallback content
  document.getElementById('document-viewer').innerHTML =
    '<div class="error">Unable to load document. Please try again.</div>'
}

Runtime Error Handling​

function updateDocumentViewer(docId) {
  try {
    // Validate docId before updating
    if (!docId || typeof docId !== 'string' || docId.trim().length === 0) {
      throw new Error('Invalid document ID provided')
    }

    documentViewer.destroy()
    documentViewer = new AlphaSenseWidget({
      target: '#document-viewer',
      widgetType: 'documentViewer',
      documentViewerParams: {docId: docId.trim()},
    }).init()
  } catch (error) {
    console.error('Failed to update document viewer:', error.message)

    // Show error state
    document.getElementById('document-viewer').innerHTML =
      `<div class="error">Failed to load document: ${docId}</div>`
  }
}

Loading States​

function updateDocumentViewer(docId) {
  // Show loading state
  document.getElementById('document-viewer').innerHTML =
    '<div class="loading">Loading document...</div>'

  try {
    documentViewer.destroy()
    documentViewer = new AlphaSenseWidget({
      target: '#document-viewer',
      widgetType: 'documentViewer',
      documentViewerParams: {docId},
    }).init()
  } catch (error) {
    // Handle error as shown above
  }
}

Obtaining Document IDs​

Document IDs are typically obtained from:

  1. AlphaSense API: Search and discover API responses include document IDs
  2. Widget Callbacks: Any widget supporting onDocumentClick provides the docId
  3. URL Parameters: Some widgets may pass docIds via URL parameters
// Example: Getting docId from Document List callback
const documentList = new AlphaSenseWidget({
  // ... other config
  onDocumentClick: docId => {
    console.log('Received docId:', docId) // e.g., "PR-abc123def456"
    updateDocumentViewer(docId)
  },
})

Widget Compatibility​

The Document Viewer works with any widget that supports the onDocumentClick callback:

Compatible Widgets​

Any widget supporting onDocumentClick callback and provides the docId can be used with the Document Viewer. For example:

  • ✅ Document List - Available for document browsing.
  • ✅ Generative Search - Available for citations source documents.

Best Practices​

Performance​

  • Reuse containers: Destroy and recreate widgets in the same container rather than creating multiple containers
  • Debounce updates: If users click rapidly, debounce the updateDocumentViewer function
  • Memory management: Always call destroy() before creating new widget instances

User Experience​

  • Loading states: Show loading indicators during document transitions
  • Error recovery: Provide clear error messages and retry mechanisms
  • Responsive design: Ensure the viewer works well on different screen sizes
  • Accessibility: Use semantic HTML and proper ARIA labels for the container

Development​

  • Environment configuration: Use different widgetUrl values for development, staging, and production
  • Error logging: Implement proper error logging for production debugging
  • Testing: Test with various document types and edge cases (empty docIds, network failures, etc.)