React API Reference

<VerifyKitProvider config={config}>
  <App />
</VerifyKitProvider>

<Viewer
  ref={viewerRef}
  fileBuffer={arrayBuffer}
  fileName="report.pdf"
  plugins={[layout.plugin]}
  onDocumentLoaded={(doc) => console.log('Pages:', doc.numPages)}
  onOpenFile={(file) => verification.load(file)}
  signatures={verification.signatures}
  unsignedFields={verification.unsignedFields}
  verificationStatus={verification.status}
/>

interface ViewerHandle {
  scrollToPage(n: number): void
  getStore(): ViewerStore
}

const viewerRef = useRef<ViewerHandle>(null)
viewerRef.current.scrollToPage(5)

<WelcomeScreen
  onOpenFile={(file: File) => verification.load(file)}
  title="My PDF Viewer"
  subtitle="Drag and drop a PDF here"
/>

<PdfViewer
  ref={viewerRef}
  fileBuffer={arrayBuffer}
  signatures={signatures}
  onWidgetClick={(sig, fieldName) => {}}
/>

function useVerification(): VerificationState

interface VerificationState {
  load(input: PdfInput, fileName?: string): Promise<VerificationResult>
  revalidate(): Promise<VerificationResult | null>
  reset(): void
  fileBuffer: ArrayBuffer | null
  originalFileBuffer: ArrayBuffer | null
  fileName: string
  result: VerificationResult | null
  metadata: DocumentMetadata | null
  permissions: DocumentPermissions | null
  signatures: PdfSignature[]
  unsignedFields: UnsignedSigField[]
  status: VerificationStatus | null
  isLoading: boolean
  error: LoadError | null
}

const verification = useVerification()
 
await verification.load(file)        // File, ArrayBuffer, Uint8Array, or URL
verification.signatures              // PdfSignature[]
verification.status                  // 'valid' | 'invalid' | 'warning' | ...
verification.isLoading               // boolean
verification.error                   // LoadError | null (object with name and message)
await verification.revalidate()      // Re-verify signatures on current buffer
verification.reset()                 // Clear state

function useViewerStore<T>(selector: (state: ViewerStoreState) => T): T

const scale = useViewerStore(s => s.scale)
const [page, total] = useViewerStore(s => [s.currentPage, s.totalPages])

function useViewerStoreKey<K extends keyof ViewerStoreState>(key: K): ViewerStoreState[K]

const currentPage = useViewerStoreKey('currentPage')

function useViewerStoreUpdate(): (partial: Partial<ViewerStoreState>) => void

const update = useViewerStoreUpdate()
update({ scale: 1.5, fitMode: 'none' })

function useStore(): ViewerStore

function useContainerSize(ref: React.RefObject<HTMLElement>): { width: number; height: number }

function usePinchZoom(
  ref: React.RefObject<HTMLElement>,
  onZoom: (scaleDelta: number) => void,
): void

const [layout] = useState(() => defaultLayoutPlugin())

function defaultLayoutPlugin(options?: DefaultLayoutPluginOptions): DefaultLayoutPluginResult

interface DefaultLayoutPluginOptions {
  accessibility?: AccessibilityPluginOptions
  disable?: {
    search?: boolean
    print?: boolean
    download?: boolean
    fullscreen?: boolean
    theme?: boolean
    rotation?: boolean
    selection?: boolean
    sidebar?: boolean
    signatures?: boolean
    highlights?: boolean
    openFile?: boolean
    properties?: boolean
    shortcuts?: boolean
    contextMenu?: boolean
    accessibility?: boolean
  }
  toolbar?: ToolbarPluginOptions
}
 
interface AccessibilityPluginOptions {
  initialScale?: 'compact' | 'default' | 'large' | 'extra-large'
  persist?: boolean  // default: true — save preference to localStorage
}

interface DefaultLayoutPluginResult {
  plugin: ViewerPlugin
  zoom: ZoomPluginApi
  navigation: PageNavigationPluginApi
  rotation: RotationPluginApi
  search: SearchPluginApi
  print: PrintPluginApi
  download: DownloadPluginApi
  theme: ThemePluginApi
  fullscreen: FullscreenPluginApi
  selection: SelectionPluginApi
  scrollMode: ScrollModePluginApi
  spreadMode: SpreadModePluginApi
  signature: SignaturePluginApi
  sidebar: SidebarPluginApi
  accessibility: AccessibilityPluginApi
}

// All features
const [layout] = useState(() => defaultLayoutPlugin())
 
// Selective features
const [layout] = useState(() =>
  defaultLayoutPlugin({
    disable: { print: true, download: true, contextMenu: true },
  })
)
 
<Viewer fileBuffer={buffer} plugins={[layout.plugin]} />

interface VerifyKitConfig extends VerifyKitCoreConfig {
  workerUrl: string            // REQUIRED. URL to the PDF.js worker script.
  cMapUrl?: string              // Default: '/cmaps/'
  standardFontDataUrl?: string  // Default: '/standard_fonts/'
  theme?: ThemeConfig
  embeddedFont?: boolean | string
  toolbar?: ToolbarConfig
  locale?: string               // Default: 'en'
  translations?: Partial<TranslationStrings>
}
 
interface ThemeConfig {
  mode?: 'light' | 'dark' | 'system'
  overrides?: Record<string, string>  // CSS variable overrides
}

interface ToolbarConfig {
  openFile?: boolean          // default: false
  pageNavigation?: boolean    // default: true
  zoom?: boolean              // default: true
  fitMode?: boolean           // default: true
  rotation?: boolean          // default: true
  scrollMode?: boolean        // default: true
  search?: boolean            // default: true
  print?: boolean             // default: true
  download?: boolean          // default: false
  themeToggle?: boolean       // default: true
  fullscreen?: boolean        // default: true
  signaturePanel?: boolean    // default: true
  cursorTool?: boolean        // default: true
  moreMenu?: boolean          // default: true
  documentProperties?: boolean // default: true
}

interface ViewerPlugin {
  name: string
  dependencies?: string[]
  composedPlugins?: ViewerPlugin[]
 
  // Lifecycle hooks
  install?(ctx: PluginContext): void
  onDocumentLoad?(e: DocumentLoadEvent): void
  onDocumentUnload?(): void
  onPageChange?(e: PageChangeEvent): void
  onZoomChange?(e: ZoomChangeEvent): void
  onRotationChange?(e: RotationChangeEvent): void
  destroy?(): void
 
  // UI contributions
  renderToolbarSlot?: Partial<ToolbarSlots>
  sidebarTabs?: SidebarTabDefinition[]
  renderOverlay?: (props: OverlayRenderProps) => React.ReactNode
  renderRightPanel?: (props: OverlayRenderProps) => React.ReactNode
  renderPageOverlay?: (props: PageOverlayRenderProps) => React.ReactNode
  transformToolbarSlots?: (slots: ToolbarSlots) => ToolbarSlots
}

interface PluginContext {
  store: ViewerStore
  getDocument(): PDFDocumentProxy | null
  scrollToPage(pageNum: number): void
  getScrollContainer(): HTMLElement | null
  getViewerContainer(): HTMLElement | null
  registerShortcut(shortcut: KeyboardShortcut): () => void
  onOpenFile?: (file: File) => void
  onRevalidate?: () => void
  t(key: string): string
}

interface ViewerHandle {
  scrollToPage(n: number): void
  getStore(): ViewerStore
}

interface ViewerStore {
  get<K extends keyof ViewerStoreState>(key: K): ViewerStoreState[K]
  getState(): ViewerStoreState
  update(partial: Partial<ViewerStoreState>): void
  subscribe<K extends keyof ViewerStoreState>(
    key: K,
    listener: (newVal: ViewerStoreState[K], oldVal: ViewerStoreState[K]) => void,
  ): () => void
  subscribeAll(listener: (key: string, newVal: unknown, oldVal: unknown) => void): () => void
  batch(fn: () => void): void
  reset(): void
  destroy(): void
}

interface DocumentLoadEvent {
  document: PDFDocumentProxy
  numPages: number
}
 
interface PageChangeEvent {
  currentPage: number
  previousPage: number
}
 
interface ZoomChangeEvent {
  scale: number
  previousScale: number
  fitMode: ViewerStoreState['fitMode']
}
 
interface RotationChangeEvent {
  rotation: ViewerStoreState['rotation']
  previousRotation: ViewerStoreState['rotation']
}

interface KeyboardShortcut {
  id: string
  key: string
  ctrl?: boolean
  shift?: boolean
  alt?: boolean
  handler: (e: KeyboardEvent) => void
  allowInInput?: boolean
  description?: string
}

interface SidebarTabDefinition {
  id: string
  label: string
  icon: React.ReactNode
  component: React.ComponentType<{ store: ViewerStore }>
  canRender?: (state: ViewerStoreState) => boolean
  order: number
}

interface ToolbarSlots {
  SearchPopover?: ToolbarSlotRender
  GoToPreviousPage?: ToolbarSlotRender
  CurrentPageInput?: ToolbarSlotRender
  NumberOfPages?: ToolbarSlotRender
  GoToNextPage?: ToolbarSlotRender
  ZoomOut?: ToolbarSlotRender
  Zoom?: ToolbarSlotRender
  ZoomIn?: ToolbarSlotRender
  Rotate?: ToolbarSlotRender
  CursorTool?: ToolbarSlotRender
  OpenFile?: ToolbarSlotRender
  Download?: ToolbarSlotRender
  Print?: ToolbarSlotRender
  ThemeToggle?: ToolbarSlotRender
  Fullscreen?: ToolbarSlotRender
  MoreMenu?: ToolbarSlotRender
  [custom: string]: ToolbarSlotRender | undefined
}
 
type ToolbarSlotRender = (props: { store: ViewerStore }) => React.ReactNode

interface LoadError {
  /** Semantic error type for programmatic handling */
  name: LoadErrorName
  /** Human-readable error message */
  message: string
}

type LoadErrorName =
  | 'InvalidPDFException'
  | 'MissingPDFException'
  | 'UnexpectedResponseException'
  | 'PasswordException'
  | 'AbortException'
  | 'FormatError'
  | 'NetworkError'
  | 'UnsupportedInputError'
  | 'VerificationError'
  | 'UnknownErrorException'

function classifyPdfError(error: unknown): LoadError

function createLoadError(name: LoadErrorName, message: string): LoadError

interface StatusCfg {
  color: string
  bg: string
  stripe: string
  title: string
}

function statusTextColor(status: VerificationStatus): string

function getStatusSentence(sig: PdfSignature): string

function getInvalidSub(sig: PdfSignature): string

function getPillLabel(sig: PdfSignature): string

function getInitials(name: string): string

function getDisplayStatus(sig: PdfSignature): VerificationStatus

function overallStatus(result: VerificationResult): VerificationStatus

interface CheckItem {
  status: VerificationStatus
  label: string
  text: string
  detail?: string
}

interface MiniCheckItem {
  status: VerificationStatus
  label: string
}

interface SummaryLine {
  status: VerificationStatus
  text: string
}

function buildChecks(sig: PdfSignature): CheckItem[]

function buildMiniChecks(sig: PdfSignature): MiniCheckItem[]

function buildSummaryLines(sig: PdfSignature): SummaryLine[]

function isLtvEnabled(sig: PdfSignature): boolean

function getCN(s: string): string

function getO(s: string): string

function getField(s: string, key: string): string

function fmtDateLong(d: Date | string): string
// Example: "Saturday, March 15, 2025, 02:30:45 PM UTC"

function fmtDateShort(d: Date | string): string
// Example: "Mar 15, 2025, 02:30:45 PM UTC"

function fmtDateCompact(d: Date | string | null | undefined): string
// Example: "Mar 15, 2025, 14:30"

function fmtDatePanel(d: Date | string | null | undefined): string
// Example: "Mar 15, 2025, 14:30:45 UTC"

function uint8ToBase64(bytes: Uint8Array): string

function downloadBlob(blob: Blob, name: string): void

function exportCertAsPem(cert: CertificateInfo, filename: string): void

function exportCertAsDer(cert: CertificateInfo, filename: string): void

function safeName(cert: CertificateInfo): string

async function swapSignatureAppearances(
  pdfBytes: Uint8Array,
  signatures: PdfSignature[],
): Promise<Uint8Array>

async function hasAcro6Appearances(pdfBytes: Uint8Array): Promise<boolean>

interface RecentFileEntry {
  fileName: string
  fileSize: number
  lastOpened: string          // ISO date string
  signatureCount?: number
  overallStatus?: string
}

function loadRecentFiles(): RecentFileEntry[]

function addRecentFile(entry: RecentFileEntry): RecentFileEntry[]

function clearRecentFiles(): RecentFileEntry[]

<CoreViewer
  ref={viewerRef}
  fileBuffer={buffer}
  fileName="report.pdf"
  plugins={[layout.plugin]}
  onDocumentLoaded={(doc) => console.log(doc.numPages)}
  renderError={(err) => <MyErrorUI error={err} />}
/>

interface CoreViewerHandle {
  scrollToPage(n: number): void
  getStore(): ViewerStore
}

interface CoreViewerSlots {
  /** Toolbar area content from plugins */
  toolbar: React.ReactNode
  /** Sidebar area content from plugins */
  sidebar: React.ReactNode
  /** The scrollable page area */
  pages: React.ReactNode
  /** Overlays (findbar, message bar, etc.) */
  overlays: React.ReactNode[]
  /** All resolved toolbar slots */
  toolbarSlots: ToolbarSlots
  /** All resolved sidebar tabs */
  sidebarTabs: SidebarTabDefinition[]
}

interface PageRendererProps {
  page: PDFPageProxy
  scale: number
  rotation: 0 | 90 | 180 | 270
  pageNum: number
  totalPages: number
  linkService: any
  /** Additional overlays (signature widgets, highlights, etc.) */
  children?: React.ReactNode
}

function createViewerStore(overrides?: Partial<ViewerStoreState>): ViewerStore

const store = createViewerStore({ scale: 1.5, themeMode: 'dark' })
store.get('scale')       // 1.5
store.update({ scale: 2 })
store.subscribe('scale', (newVal, oldVal) => console.log(newVal))

const INITIAL_STATE: ViewerStoreState = {
  document: null,
  fileBuffer: null,
  originalFileBuffer: null,
  fileName: '',
  loadState: 'idle',
  loadError: null,
  currentPage: 1,
  totalPages: 0,
  scale: 1.2,
  fitMode: 'none',
  rotation: 0,
  scrollMode: 'vertical',
  spreadMode: 'none',
  cursorTool: 'select',
  themeMode: 'light',
  uiFontScale: 'default',
  isFullscreen: false,
  signatures: [],
  unsignedFields: [],
  verificationStatus: null,
  sidebarOpen: false,
  sidebarTab: 'thumbnails',
  sigPanelOpen: false,
  findOpen: false,
  propertiesModalOpen: false,
  shortcutHelpOpen: false,
  contextMenuPos: null,
  sigModalIndex: null,
  sigModalFieldName: '',
  sigModalTab: 'details',
  passwordNeeded: false,
  passwordError: false,
}

const ViewerStoreContext: React.Context<ViewerStore | null>

function downloadPdf(store: ViewerStore): void

function rotateCW(store: ViewerStore): void

function rotateCCW(store: ViewerStore): void

function toggleFullscreen(store: ViewerStore, element?: HTMLElement | null): void

function resolvePlugins(plugins: ViewerPlugin[]): ViewerPlugin[]

function collectToolbarSlots(plugins: ViewerPlugin[]): ToolbarSlots

function collectSidebarTabs(plugins: ViewerPlugin[]): SidebarTabDefinition[]

interface ZoomPluginApi {
  zoomIn(): void
  zoomOut(): void
  zoomTo(scale: number): void
  setFitMode(mode: 'none' | 'width' | 'page'): void
}

interface PageNavigationPluginApi {
  goToPage(n: number): void
  goToPreviousPage(): void
  goToNextPage(): void
  goToFirstPage(): void
  goToLastPage(): void
}

interface RotationPluginApi {
  rotateCW(): void
  rotateCCW(): void
  setRotation(r: 0 | 90 | 180 | 270): void
}

interface SearchPluginApi {
  open(): void
  close(): void
  toggle(): void
}

interface PrintPluginApi {
  print(): void
}

interface DownloadPluginApi {
  download(): void
}

interface ThemePluginApi {
  toggleTheme(): void
  setTheme(mode: 'light' | 'dark'): void
  getTheme(): 'light' | 'dark'
}

interface FullscreenPluginApi {
  enterFullscreen(): void
  exitFullscreen(): void
  toggleFullscreen(): void
}

interface SelectionPluginApi {
  setCursorTool(tool: 'select' | 'hand'): void
  toggleHand(): void
}

interface ScrollModePluginApi {
  setScrollMode(mode: 'vertical' | 'horizontal' | 'wrapped' | 'page'): void
}

interface SpreadModePluginApi {
  setSpreadMode(mode: 'none' | 'odd' | 'even'): void
}

interface SignaturePluginApi {
  openPanel(): void
  closePanel(): void
  togglePanel(): void
}

interface SidebarPluginApi {
  open(tabId?: string): void
  close(): void
  toggle(tabId?: string): void
  setTab(tabId: string): void
}

interface AccessibilityPluginApi {
  setFontScale(scale: 'compact' | 'default' | 'large' | 'extra-large'): void
  getFontScale(): 'compact' | 'default' | 'large' | 'extra-large'
}

interface DefaultLayoutPluginOptions {
  accessibility?: AccessibilityPluginOptions
  toolbar?: ToolbarPluginOptions
  disable?: {
    search?: boolean
    print?: boolean
    download?: boolean
    fullscreen?: boolean
    theme?: boolean
    rotation?: boolean
    selection?: boolean
    sidebar?: boolean
    signatures?: boolean
    highlights?: boolean
    openFile?: boolean
    properties?: boolean
    shortcuts?: boolean
    contextMenu?: boolean
    accessibility?: boolean
  }
}
 
interface AccessibilityPluginOptions {
  initialScale?: 'compact' | 'default' | 'large' | 'extra-large'
  persist?: boolean  // default: true — save preference to localStorage
}

interface DefaultLayoutPluginResult {
  plugin: ViewerPlugin
  zoom: ZoomPluginApi
  navigation: PageNavigationPluginApi
  rotation: RotationPluginApi
  search: SearchPluginApi
  print: PrintPluginApi
  download: DownloadPluginApi
  theme: ThemePluginApi
  fullscreen: FullscreenPluginApi
  selection: SelectionPluginApi
  scrollMode: ScrollModePluginApi
  spreadMode: SpreadModePluginApi
  signature: SignaturePluginApi
  sidebar: SidebarPluginApi
  accessibility: AccessibilityPluginApi
}

// Root dialog container (controls open/close state)
const Dialog: React.FC<RadixDialogProps>
 
// Semi-transparent backdrop overlay
const DialogOverlay: React.ForwardRefComponent<HTMLDivElement>
 
// Centered dialog content panel (includes overlay automatically)
const DialogContent: React.ForwardRefComponent<HTMLDivElement>
 
// Dialog title heading
const DialogTitle: React.ForwardRefComponent<HTMLHeadingElement>
 
// Flexbox column container for dialog header area
const DialogHeader: React.FC<React.HTMLAttributes<HTMLDivElement>>
 
// Close button (triggers onOpenChange(false))
const DialogClose: React.FC<RadixDialogCloseProps>

import { Dialog, DialogContent, DialogTitle, DialogHeader, DialogClose } from '@trexolab/verifykit-react'
 
<Dialog open={isOpen} onOpenChange={setIsOpen}>
  <DialogContent style={{ maxWidth: 480 }}>
    <DialogHeader>
      <DialogTitle>Certificate Details</DialogTitle>
    </DialogHeader>
    <p>Dialog body content</p>
    <DialogClose>Close</DialogClose>
  </DialogContent>
</Dialog>

// Root dialog wrapper (absolute positioned within viewer)
function ViewerDialog(props: {
  open: boolean
  onOpenChange?: (open: boolean) => void
  children: React.ReactNode
}): React.ReactNode
 
// Blurred backdrop overlay (covers only the viewer area)
function ViewerDialogOverlay(props: {
  onClick?: () => void
}): React.ReactNode
 
// Centered content panel with border, shadow, and entrance animation
function ViewerDialogContent(props: {
  children: React.ReactNode
  style?: React.CSSProperties
  onClose?: () => void
}): React.ReactNode
 
// Dialog title heading (h2 element)
function ViewerDialogTitle(props: {
  children: React.ReactNode
  style?: React.CSSProperties
}): React.ReactNode

function Toolbar(props: { slots: ToolbarSlots; store: ViewerStore }): React.ReactNode

function ToolbarDivider(): React.ReactNode

interface ToolbarPluginOptions {
  /** Transform toolbar slots -- add, remove, or reorder */
  transform?: (slots: ToolbarSlots) => ToolbarSlots
}

type Locale = 'en' | 'fr' | 'de' | 'es' | 'ar' | 'ja' | 'zh' | string

function t(key: string, locale?: string): string

function setLocale(locale: string): void
function getLocale(): string

function registerLocale(locale: string, strings: Partial<TranslationStrings>): void

import { registerLocale, setLocale } from '@trexolab/verifykit-react'
 
registerLocale('fr', {
  'toolbar.print': 'Imprimer',
  'toolbar.download': 'Telecharger',
  'status.valid': 'Valide',
  'status.invalid': 'Invalide',
})
setLocale('fr')

function getAvailableLocales(): string[]