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"
/>

function useVerification(): VerificationState

interface VerificationState {
  load(input: PdfInput, fileName?: string): Promise<VerificationResult>
  revalidate(): Promise<VerificationResult | null>
  applyPassword(pwd: string): Promise<void>
  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

// Only if your app unlocks the PDF outside VerifyKit's viewer.
await verification.applyPassword(userPassword)

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

type Breakpoint = 'xs' | 'sm' | 'md' | 'lg'
 
function useContainerSize(
  ref: React.RefObject<HTMLElement | null>
): { width: number; height: number; breakpoint: Breakpoint }

.verifykit-root[data-breakpoint="xs"] .my-panel { display: none; }

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

function defaultLayoutPlugin(options?: DefaultLayoutPluginOptions): DefaultLayoutPluginResult

interface DefaultLayoutPluginOptions {
  accessibility?: AccessibilityPluginOptions
  /** Override zoom range and step. See {@link ZoomPluginOptions}. */
  zoom?: ZoomPluginOptions
  /** Page navigation. See {@link PageNavigationPluginOptions}. */
  pageNavigation?: PageNavigationPluginOptions
  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 ZoomPluginOptions {
  /** Minimum scale. Default `0.25` (25%). */
  minScale?: number
  /** Maximum scale. Default `10` (1000%). */
  maxScale?: number
  /** Scale delta per zoom-in / zoom-out click. Default `0.15`. */
  step?: number
}
 
interface PageNavigationPluginOptions {
  /**
   * Floating previous/next control over the bottom of the page in single-page
   * scroll mode, revealed while the pointer is over the document. Default `true`.
   *
   * Single-page is the one mode where scrolling cannot reach the next page, so
   * turning this off leaves the toolbar as the only way forward.
   */
  floatingNav?: 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
}

// 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
}

npm pack pdfjs-dist@5.5.207 --pack-destination /tmp \
  && tar -xzOf /tmp/pdfjs-dist-5.5.207.tgz package/legacy/build/pdf.worker.min.mjs \
     > public/pdf.worker.min.mjs

interface ViewerPlugin {
  name: string
  dependencies?: string[]
  composedPlugins?: ViewerPlugin[]
 
  // Lifecycle hooks
  install?(ctx: ViewerPluginContext): 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>
  renderMenuItems?: MenuItemsRender   // 0.7.0+
  renderContextMenuItems?: ContextMenuItemsRender  // unreleased
  menuOrder?: number                  // 0.7.0+ — lower renders earlier (default 50)
  menuGroup?: string                  // 0.7.0+ — section label for the divider
  sidebarTabs?: SidebarTabDefinition[]
  renderOverlay?: (props: OverlayRenderProps) => React.ReactNode
  renderRightPanel?: (props: OverlayRenderProps) => React.ReactNode
  renderPageOverlay?: (props: PageOverlayRenderProps) => React.ReactNode
  transformToolbarSlots?: (slots: ToolbarSlots) => ToolbarSlots
}

interface ViewerPluginContext {
  store: ViewerStore
  getDocument(): PDFDocumentProxy | null
  scrollToPage(pageNum: number): void
  getScrollContainer(): HTMLElement | null
  getViewerContainer(): HTMLElement | null
  registerShortcut(shortcut: KeyboardShortcut): () => void
  getPlugins(): ViewerPlugin[]        // unreleased
  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: (state: ViewerStoreState, prev: ViewerStoreState) => void): () => void
  batch(fn: () => void): void
  reset(): void
  destroy(): void
}

type FitMode    = 'none' | 'width' | 'page'
type ScrollMode = 'vertical' | 'horizontal' | 'page'
type SpreadMode = 'none' | 'odd' | 'even'
type CursorTool = 'select' | 'hand'
type SidebarTab = string   // tab id; plugins register their own

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<SidebarTabProps>
  canRender?: (state: ViewerStoreState) => boolean
  order: number
}
 
interface SidebarTabProps {
  store: ViewerStore
}

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
  FontScale?: ToolbarSlotRender
  ThemeToggle?: ToolbarSlotRender
  Fullscreen?: ToolbarSlotRender
  MoreMenu?: ToolbarSlotRender
  [custom: string]: ToolbarSlotRender | undefined
}
 
type ToolbarSlotRender = (props: ToolbarSlotProps) => React.ReactNode
 
interface ToolbarSlotProps {
  store: ViewerStore
  /** Slots the toolbar could not fit at the current width (0.7.0+). */
  overflowSlots?: string[]
  /** Collect every plugin's menu contributions — passed to the `MoreMenu` slot (0.7.0+). */
  renderMenuItems?: (onClose: () => void) => CollectedMenuItems[]
}

type MenuItemsRender = (props: MenuItemRenderProps) => React.ReactNode
 
interface MenuItemRenderProps {
  store: ViewerStore
  /** Registered slots the toolbar could not fit, in the order they were dropped. */
  overflowSlots: string[]
  /** True when `slot` is registered in the toolbar but not currently visible. */
  isOverflowed(slot: string): boolean
  /** Close the menu. Call after running an action. */
  onClose(): void
}
 
/** One plugin's contribution, as gathered by `collectMenuItems`. */
interface CollectedMenuItems {
  name: string    // contributing plugin name — used as the React key
  group: string   // section label; a divider is drawn where this changes
  node: React.ReactNode
}

type ContextMenuItemsRender = (props: ContextMenuItemRenderProps) => React.ReactNode
 
interface ContextMenuItemRenderProps {
  store: ViewerStore
  /** Close the menu. Call after running an action. */
  onClose(): void
}

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

function exportCertChainAsPem(
  certs: readonly CertificateInfo[],
  filename: string,
): void

async function exportCertChainAsPkcs7(
  certs: readonly CertificateInfo[],
  filename: string,
): Promise<void>

function exportCertChainAsZip(
  certs: readonly CertificateInfo[],
  filename: string,
): void

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' | '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[]