Skip to main content

Getting started with the React UI

This guide walks you through integrating the ARender viewer into your own application — step by step, from installation to displaying your first document in the browser.

The ARender viewer is distributed as the arender-ui npm package. It registers an <arender-element> Web Component that integrates into any framework — React, Angular, Vue, Svelte, or plain HTML. The viewer communicates with the ARender rendition backend over REST.

Don't have a project yet? You can create a fresh React application to follow along:

npm create vite@latest my-app -- --template react-ts
cd my-app

Then continue with the steps below.

Prerequisites​

  • Node.js 20+ and a package manager (npm or yarn)

Step 1 — Install the ARender package​

Open a terminal at the root of your project and install the arender-ui package:

npm install arender-ui@2026.2.0 --registry=https://npm.cloudsmith.io/uxopian/uxopian-public

Step 2 — Configure the dev server proxy​

The viewer needs to reach the rendition backend. In development, your dev server's built-in proxy handles this — no external reverse proxy needed.

note

Uxopian provides a shared demo rendition backend at https://rendition.demo.arender.uxopian.com — available to all, no credentials or installation required. This lets you test the viewer right away. Deploying your own backend is covered in the Installation section.

Add the following proxy configuration to vite.config.ts:

vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      '/documents': {
        target: 'https://rendition.demo.arender.uxopian.com',
        changeOrigin: true,
      },
      '/registry/documents': {
        target: 'https://rendition.demo.arender.uxopian.com',
        changeOrigin: true,
      },
    },
  },
})
tip

To connect to your own backend instead of the demo, change each target to your backend URL (e.g. http://localhost:8761 for Docker Compose). In production, replace the dev proxy with a reverse proxy (Nginx, Ingress) or a BFF. See Docker Compose for deployment guides.

For other frameworks (Next.js, Nuxt, CRA, webpack…), configure your dev server proxy to forward /documents and /registry/documents to the rendition backend. Annotation requests are served under /documents/{documentId}/annotations, so they are covered by the /documents prefix. Refer to your framework's documentation.

Step 3 — Embed the viewer​

The <arender-element> is a Web Component — a standard HTML element you can drop into any template or JSX just like a <video> or <input>. It encapsulates the entire ARender viewer: no JavaScript instantiation required to display it. You configure it through HTML attributes.

Web Component attributes​

The table below lists the attributes you can set directly on the element:

AttributeRequiredDescription
renditionYesURL of the ARender rendition backend. Use / when proxied with Vite, or http://localhost:4200/ with Angular (see Step 3).
documentNoQuery string of the parameters identifying the document to open on startup, e.g. url=https://example.com/doc.pdf.

Set document directly as an HTML attribute to open a document on startup — no JavaScript needed. The attribute is read once, when the component mounts. To load a different document at runtime, use the JavaScript API.

note

The document attribute takes the same query string as the JavaScript API: url=… for a document reachable over HTTP, uuid=… for an already-resolved ARender document ID, or the parameters your repository expects.

Every value must be URL-encoded, so bind the attribute instead of hardcoding it — document={`url=${encodeURIComponent(docUrl)}`} — and let encodeURIComponent do the escaping. See Web Component → Parameter contract.

Copy the following into your src/App.tsx file, replacing its entire contents:

src/App.tsx
import { useEffect } from 'react'
import type { ARenderHTMLElement } from 'arender-ui'

// Move these declarations to a global.d.ts in a real project
declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'arender-element': React.HTMLAttributes<HTMLElement> & {
        rendition?: string
        document?: string
      }
    }
  }
}
declare global {
  interface Window { ARender: ARenderHTMLElement }
}

const DOC_URL = 'https://www.uxopian.com/hubfs/PDFReference15_v5.pdf'

function App() {
  useEffect(() => { import('arender-ui') }, [])

  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <arender-element
        rendition="/"
        document={`url=${encodeURIComponent(DOC_URL)}`}
      />
    </div>
  )
}

export default App
Loading strategy

The examples below use a dynamic import() inside a lifecycle hook (useEffect, onMounted, etc.) rather than a static import at the top of the file. This is intentional for SSR compatibility: arender-ui registers a Web Component using browser APIs (window, document, customElements) that do not exist in Node.js. A static import would crash the build in SSR frameworks like Next.js, Nuxt, or SvelteKit.

If your application is purely client-side (no SSR), a static import at the top of the file works just as well:

import 'arender-ui'

Step 4 — Start the dev server​

With the viewer embedded, start your development server and open it in your browser.

If you created a fresh Vite project (as shown in the introduction), run:

npm run dev

Vite will print a local URL — usually http://localhost:5173. Open it in your browser and you should see the ARender viewer loading the sample PDF.

If you use a different package manager, the equivalent command is:

Package managerCommand
yarnyarn dev
pnpmpnpm dev
bunbun dev

For other frameworks, use your usual start command (e.g. npm start for CRA).

tip

If the viewer loads but no document appears, double-check the proxy configuration in Step 3 — the /documents and /registry/documents paths must both be proxied to the rendition backend.

Step 5 — Load a document dynamically​

To change the displayed document at runtime, call window.ARender.openDocument(params) with the same query string the document attribute takes. The most recent call wins, and calls made before the viewer finishes mounting are queued automatically — no need to wait for any event.

The examples below wrap the document URL in encodeURIComponent: the viewer forwards your parameters to the backend untouched, so encoding each value is the caller's responsibility. It matters as soon as a value carries its own query string, such as a pre-signed URL.

Replace your src/App.tsx with the following complete file:

src/App.tsx
import { useEffect } from 'react'
import type { ARenderHTMLElement } from 'arender-ui'

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'arender-element': React.HTMLAttributes<HTMLElement> & {
        rendition?: string
        document?: string
      }
    }
  }
}
declare global {
  interface Window { ARender: ARenderHTMLElement }
}

const DOC_URL = 'https://www.uxopian.com/hubfs/PDFReference15_v5.pdf'
const MAIL_URL = 'https://www.uxopian.com/hubfs/ARender-Mail_viewer_use_case.msg'

function App() {
  useEffect(() => { import('arender-ui') }, [])

  function changeDocument() {
    window.ARender.openDocument(`url=${encodeURIComponent(MAIL_URL)}`)
  }

  return (
    <div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
      <div>
        <button onClick={changeDocument}>Change document</button>
      </div>
      <arender-element
        rendition="/"
        document={`url=${encodeURIComponent(DOC_URL)}`}
        style={{ flex: 1 }}
      />
    </div>
  )
}

export default App

Sample documents​

These public URLs can be used for testing (the demo rendition already authorizes https://www.uxopian.com/):

  • PDF: https://www.uxopian.com/hubfs/PDFReference15_v5.pdf
  • Image: https://www.uxopian.com/hubfs/example_image_comparison_unmodified.jpg
  • Email: https://www.uxopian.com/hubfs/ARender-Mail_viewer_use_case.msg

Next steps​

Last updated on