@whdigitalbuild/forge-viewer-react

React bindings for Autodesk Forge Viewer

React components and hooks for integrating Autodesk Forge Viewer into your React applications with ease.

🚀 Features

• ForgeViewer Component - Drop-in React component for Forge Viewer
• Custom Hooks - React hooks for viewer state management
• TypeScript Support - Full type safety
• Event Handling - React-friendly event system
• Context API - Share viewer instance across components
• Error Boundaries - Built-in error handling

📦 Installation

npm install @whdigitalbuild/forge-viewer-react @whdigitalbuild/forge-viewer-core

🔧 Quick Start

import { ForgeViewer } from '@whdigitalbuild/forge-viewer-react';

function App() {
  return (
    <ForgeViewer
      urn="dXJuOmFkc2sud2lwcHJvZDpmcy5maWxlOnZmLnlvdXItZmlsZS1pZD92ZXJzaW9uPTE"
      accessToken="your-3-legged-token"
      style={{ width: '100%', height: '100vh' }}
      onModelLoaded={(model) => console.log('Model loaded!', model)}
      onSelectionChanged={(dbIds) => console.log('Selected:', dbIds)}
    />
  );
}

📚 Examples

Load Model from ACC URL

<ForgeViewer
  accUrl="https://acc.autodesk.com/docs/files/projects/..."
  accessToken={token}
  onModelLoaded={(model) => console.log('Loaded:', model)}
/>

Use Viewer Context

import { ForgeViewer, useViewerContext } from '@whdigitalbuild/forge-viewer-react';

function ViewerControls() {
  const { viewer, isLoading } = useViewerContext();

  const handleFitToView = () => {
    if (viewer) {
      viewer.fitToView();
    }
  };

  return (
    <button onClick={handleFitToView} disabled={isLoading}>
      Fit to View
    </button>
  );
}

function App() {
  return (
    <ForgeViewer urn="..." accessToken="...">
      <ViewerControls />
    </ForgeViewer>
  );
}

Color Elements

import { ForgeViewer } from '@whdigitalbuild/forge-viewer-react';
import { ColoringEngine } from '@whdigitalbuild/forge-viewer-core';

function App() {
  const handleViewerInit = (viewer: Autodesk.Viewing.GuiViewer3D) => {
    const coloringEngine = new ColoringEngine(viewer);
    
    // Color elements red
    coloringEngine.applyColors({
      123: { r: 1, g: 0, b: 0 },
      456: { r: 1, g: 0, b: 0 }
    });
  };

  return (
    <ForgeViewer
      urn="..."
      accessToken="..."
      onViewerInitialized={handleViewerInit}
    />
  );
}

Handle Selection

function App() {
  const [selectedIds, setSelectedIds] = useState<number[]>([]);

  return (
    <div>
      <ForgeViewer
        urn="..."
        accessToken="..."
        onSelectionChanged={setSelectedIds}
      />
      <div>Selected Elements: {selectedIds.join(', ')}</div>
    </div>
  );
}

Load Multiple Models

<ForgeViewer
  accessToken="..."
  models={[
    { urn: 'model-1-urn' },
    { urn: 'model-2-urn' },
    { accUrl: 'https://acc.autodesk.com/...' }
  ]}
  onModelLoaded={(model) => console.log('Model loaded:', model)}
/>

🎯 Component Props

ForgeViewer

| Prop | Type | Description | |------|------|-------------| | urn | string | Model URN (derivative format) | | urnType | 'document' \| 'derivative' | URN type (default: 'derivative') | | accUrl | string | ACC/BIM360 URL | | dataExchangeConfig | object | Data Exchange configuration | | accessToken | string \| () => Promise<string> | OAuth token or token provider | | viewMode | '3d' \| '2d' | View mode (default: '3d') | | extensions | string[] | Extensions to load | | className | string | CSS class name | | style | CSSProperties | Inline styles | | onViewerInitialized | (viewer) => void | Viewer initialized callback | | onModelLoaded | (model) => void | Model loaded callback | | onSelectionChanged | (dbIds) => void | Selection changed callback | | onCameraChanged | (camera) => void | Camera changed callback | | onError | (error) => void | Error callback |

🪝 Custom Hooks

useViewerContext()

Access viewer instance and state from any child component:

const { viewer, viewerCore, isLoading, error } = useViewerContext();

useForgeViewer()

Alternative hook for more control:

const { viewer, isReady } = useForgeViewer(containerRef, {
  accessToken: token,
  extensions: ['Autodesk.DocumentBrowser']
});

🎨 Styling

The viewer container is styled with:

{
  width: 100%;
  height: 100%;
  position: relative;
}

Override with className or style props:

<ForgeViewer
  urn="..."
  accessToken="..."
  className="my-viewer"
  style={{ height: '600px', border: '1px solid #ccc' }}
/>

🔑 Authentication

Provide a 3-legged OAuth token with data:read scope:

// Static token
<ForgeViewer accessToken="eyJhbGciOiJIUzI1..." />

// Token provider function (recommended)
const getToken = async () => {
  const response = await fetch('/api/token');
  return response.text();
};

<ForgeViewer accessToken={getToken} />

🐛 Error Handling

import { ErrorBoundary } from '@whdigitalbuild/forge-viewer-react';

<ErrorBoundary>
  <ForgeViewer
    urn="..."
    accessToken="..."
    onError={(error) => console.error('Viewer error:', error)}
  />
</ErrorBoundary>

📝 License

MIT © Woh Hup Digital

🤝 Contributing

Issues and pull requests are welcome!

📧 Support

For support, contact Woh Hup Digital team.