API
Types
TypeScript type reference for KViewer
All types are importable from kviewer:
import type {
AddFormFieldPayload,
AddTabOptions,
CheckboxStyle,
ExportPdfOptions,
FormFieldDefinition,
FormFieldOrigin,
FormFieldType,
FormFieldValue,
SignatureData,
SignatureHandlers,
ViewerTabItem,
ViewMode,
} from 'kviewer'
ExportPdfOptions
Options for KViewer.exportPdf().
interface ExportPdfOptions {
/** Burn annotations into PDF page content (non-editable). Default: false */
flatten?: boolean
/** Trigger browser file download. Default: false */
download?: boolean
/** Custom filename for download. Auto-generated if omitted. */
fileName?: string
/** Keep unmodified native PDF annotations. Default: false */
preserveOriginalAnnotations?: boolean
}
ViewerTabItem
Defines a tab in KViewerTabs.
interface ViewerTabItem {
/** Unique tab identifier */
id: string
/** Display label in the tab bar */
label: string
/** PDF source: URL string, Uint8Array, or pdfjs-dist init params */
source: string | Uint8Array | object
/** Lucide icon name. Default: 'i-lucide-file-text' */
icon?: string
/** Whether the tab can be closed. Default: true */
closable?: boolean
/** View mode override for this tab */
viewMode?: ViewMode
/** Zoom override for this tab */
zoom?: number
/** Shape detection override for this tab */
shapeDetection?: boolean
/** Execute embedded PDF JavaScript for this document. Overrides
* `KViewerTabs.scripting` when set. Default: undefined (inherit). */
scripting?: boolean
}
ViewerMenuItem
Items passed to <KViewer :menu-items> (or <KViewerTabs :menu-items>) are rendered at the bottom of the built-in burger menu. Three shapes are supported:
type ViewerMenuItem =
| ViewerMenuButtonItem
| ViewerMenuCheckboxItem
| ViewerMenuSeparatorItem
interface ViewerMenuButtonItem {
type: 'button'
key: string // stable id for Vue list rendering
label: string
icon?: string // any Lucide icon name (e.g. 'i-lucide-trash')
onSelect: () => void
disabled?: boolean
}
interface ViewerMenuCheckboxItem {
type: 'checkbox'
key: string
label: string
icon?: string // defaults to a checked/unchecked square
checked: boolean // keep this reactive — Vue re-renders on change
onUpdate: (checked: boolean) => void
disabled?: boolean
}
interface ViewerMenuSeparatorItem {
type: 'separator'
key: string
}
ViewerToolEntry
Entries for <KViewer :tools> (or <KViewerTabs :tools>). Each is either a built-in tool ID (a string) or a ViewerToolSlot object that renders a custom button. See Configuring the toolbar.
type ViewerToolEntry = ViewerToolId | ViewerToolSlot
type ViewerToolId =
| ViewerTopToolId // top row
| ViewerBottomToolId // second (annotation) row
| ViewerLayoutToolId // 'separator' | 'spacer'
type ViewerTopToolId =
| 'menu' | 'pageSettings' | 'zoom'
| 'hand' | 'marquee'
| 'pageInfo' | 'search'
type ViewerBottomToolId =
| 'properties'
| 'freehand' | 'freeHighlight' | 'freeText'
| 'stamp' | 'signature' | 'rectangle'
| 'formText' | 'formCheckbox' | 'formRadio' | 'formSignature'
| 'undo' | 'redo' | 'eraser'
// opt-in annotation tools (no default button)
| 'select' | 'highlight' | 'strikeout' | 'underline'
| 'circle' | 'note' | 'arrow' | 'cloud'
type ViewerLayoutToolId = 'separator' | 'spacer'
interface ViewerToolSlot {
type: 'slot'
key: string // stable id for Vue list rendering
name?: string // slot-name suffix — fills #tool-<name>; defaults to key
row?: 'top' | 'bottom' // defaults to the row of the preceding entry
}
AddTabOptions
Options for KViewerTabs.addTab().
interface AddTabOptions {
/** Insert at specific index. Default: end */
index?: number
/** Switch to the new tab. Default: true */
activate?: boolean
}
StampDefinition
Defines a stamp for the stamp annotation tool.
interface StampDefinition {
/** Unique stamp identifier */
id: string
/** Display name in stamp picker */
name: string
/** Image source (URL, SVG path, or base64) */
imageUrl: string
/** Optional preview thumbnail URL */
previewUrl?: string
/** Default width in points */
width?: number
/** Default height in points */
height?: number
}
SignatureData
Represents a saved user signature.
interface SignatureData {
/** Unique signature identifier */
id: string
/** Base64 data URL or image URL */
imageUrl: string
/** Optional display name */
name?: string
}
SignatureHandlers
Callbacks for managing signature persistence.
interface SignatureHandlers {
/** Load all saved signatures */
onLoad: () => Promise<SignatureData[]>
/** Save a new signature. Returns the saved SignatureData */
onSave: (imageUrl: string) => Promise<SignatureData>
/** Delete a signature by ID */
onDelete: (id: string) => Promise<void>
}
IAnnotationStore
Serializable annotation state. Returned by getAnnotations() and accepted by importAnnotations().
interface IAnnotationStore {
/** Unique annotation ID */
id: string
/** 1-indexed page number */
pageNumber: number
/** Serialized Konva.js shape */
konvaString: string
/** Bounding box { x, y, width, height } */
konvaClientRect: IRect
/** Author name */
title: string
/** KViewer annotation type */
type: AnnotationType
/** Annotation color (hex) */
color?: string | null
/** PDF annotation subtype */
subtype: PdfjsAnnotationSubtype
/** Font size for text annotations */
fontSize?: number | null
/** pdfjs-dist annotation type number */
pdfjsType: PdfjsAnnotationType
/** pdfjs-dist editor type number */
pdfjsEditorType: PdfjsAnnotationEditorType
/** ISO date string */
date: string
/** Text or image content */
contentsObj?: IAnnotationContentsObj | null
/** Comment thread on this annotation */
comments: IAnnotationComment[]
/** Whether the annotation can be resized */
resizable: boolean
/** Whether the annotation can be dragged */
draggable: boolean
}
AnnotationType
Enum for KViewer annotation tool types.
enum AnnotationType {
NONE = -1,
SELECT = 0,
HIGHLIGHT = 1,
STRIKEOUT = 2,
UNDERLINE = 3,
FREETEXT = 4,
RECTANGLE = 5,
CIRCLE = 6,
FREEHAND = 7,
FREE_HIGHLIGHT = 8,
SIGNATURE = 9,
STAMP = 10,
NOTE = 11,
ARROW = 12,
CLOUD = 13,
}
FormFieldValue
Represents a form field's current value.
interface FormFieldValue {
/** Internal field identifier */
fieldId: string
/** PDF field name */
fieldName: string
/** Field type */
fieldType: FormFieldType
/** Current value */
value: string | boolean | string[]
}
FormFieldType
type FormFieldType = 'text' | 'checkbox' | 'radio' | 'dropdown' | 'signature' | 'button'
FormFieldDefinition
Full definition of a PDF form field.
interface FormFieldDefinition {
id: string
pageNumber: number
fieldType: FormFieldType
fieldName: string
/** PDF user-space rect [x1, y1, x2, y2], bottom-left origin */
rect: [number, number, number, number]
readOnly: boolean
required: boolean
/** Where the field came from. Missing = 'parsed' for backward compat. */
origin?: FormFieldOrigin
/** For detected checkboxes */
shapeType?: 'rectangle' | 'circle'
/** Checkbox glyph style */
checkboxStyle?: CheckboxStyle
defaultValue?: string
maxLen?: number
multiLine?: boolean
password?: boolean
comb?: boolean
exportValue?: string
buttonValue?: string
options?: { displayValue: string; exportValue: string }[]
combo?: boolean
multiSelect?: boolean
editable?: boolean
buttonLabel?: string
/** Signature: placeholder text on the unsigned widget */
promptText?: string
/** Signature: lock other fields once signed */
lockAction?: 'all' | 'include' | 'exclude'
lockFieldNames?: string[]
fontSize?: number
fontName?: string
color?: number[]
backgroundColor?: number[]
textAlignment?: number
/** Opaque role tag for color-coding in form-edit mode */
roleId?: string
}
FormFieldOrigin
Where a form field came from. Drives whether export updates an existing PDF widget or creates a new one.
type FormFieldOrigin = 'parsed' | 'detected' | 'placed'
CheckboxStyle
Standard PDF checkbox glyph styles, per Acrobat's "Check Box Style" options.
type CheckboxStyle = 'check' | 'cross' | 'diamond' | 'circle' | 'star' | 'square'
AddFormFieldPayload
Payload accepted by KViewer.addFormField(). Only pageNumber, fieldType, and rect are required — every other field has a sensible default. The created field has origin: 'placed' so it round-trips into the PDF as a new widget on exportPdf().
interface AddFormFieldPayload {
pageNumber: number
fieldType: FormFieldType
/** PDF user-space rect [x1, y1, x2, y2], bottom-left origin */
rect: [number, number, number, number]
/** Auto-generated when omitted. Multiple widgets sharing a fieldName
* + fieldType act as one PDF field; radios with the same fieldName
* form one option group. */
fieldName?: string
/** Opaque role tag for color-coding in form-edit mode */
roleId?: string
/** Default value. Used as the initial value, too. */
defaultValue?: string
readOnly?: boolean
required?: boolean
// checkbox
checkboxStyle?: CheckboxStyle
// signature
promptText?: string
lockAction?: 'all' | 'include' | 'exclude'
lockFieldNames?: string[]
// dropdown / listbox
combo?: boolean
multiSelect?: boolean
options?: { displayValue: string; exportValue: string }[]
// text
multiLine?: boolean
password?: boolean
comb?: boolean
maxLen?: number
// radio (auto-generated when omitted)
buttonValue?: string
// appearance
fontSize?: number
fontName?: string
/** RGB color tuple in 0–1 (PDF native) */
color?: number[]
/** RGB background color tuple in 0–1 (PDF native) */
backgroundColor?: number[]
/** 0 = left, 1 = center, 2 = right */
textAlignment?: number
}
PlacedFieldDefaults
Per-field-type presets merged into every field the user places via the placement tools. Passed via the KViewer fieldDefaults prop, setFieldDefaults(), or the embed bridge. Each entry accepts the AddFormFieldPayload properties minus the ones derived from the placement gesture (pageNumber, rect, fieldType) and the auto-generated fieldName/buttonValue — rename fields via the field-placed event and updateFormField() instead.
type PlacedFieldDefaultProps = Partial<Omit<AddFormFieldPayload,
'pageNumber' | 'rect' | 'fieldType' | 'fieldName' | 'buttonValue'>>
type PlacedFieldDefaults = Partial<Record<FormFieldType, PlacedFieldDefaultProps>>
const fieldDefaults: PlacedFieldDefaults = {
signature: { promptText: 'Sign here', lockAction: 'all' },
text: { fontSize: 12 },
}
SignatureFieldStatus
Signed-state snapshot of one signature widget, returned by getSignatureFieldStatus() and carried by the signed-status-changed event. signed is true when the widget holds a signature image applied in this session or the source PDF already carries a digital signature for the field.
interface SignatureFieldStatus {
id: string
fieldName: string
pageNumber: number
signed: boolean
/** Present when the field is tagged with a host role */
roleId?: string
}
ViewMode
type ViewMode = 'fit-width' | 'fit-page' | 'fit-height'
IAnnotationComment
interface IAnnotationComment {
id: string
title: string
date: string
content: string
status?: CommentStatus
}
enum CommentStatus {
Accepted = 'Accepted',
Rejected = 'Rejected',
Cancelled = 'Cancelled',
Completed = 'Completed',
None = 'None',
Closed = 'Closed',
}
IAnnotationContentsObj
interface IAnnotationContentsObj {
text: string
image?: string // Base64 encoded
}