Public API
Everything below comes from json-pdf-designer. The generation/
bindings/chart-palette/type subset is also available React-free from
json-pdf-designer/server — see Server-only usage.
The PDF preview lives in a third entry point, json-pdf-designer/preview
— listed at the end of this page.
// The preset component
Designer // the full React canvas (toolbar + list + rulers + zoom + bands)
type DesignerProps
// Composition — build your own editor layout (see "Composing the Designer")
DesignerProvider // holds all the editor state; every part below needs it above
type DesignerProviderProps
// The 10 placeable parts. DesignerSidebar is convenience: it composes the
// seven content parts with the tab gate <Designer> uses.
DesignerCanvas, DesignerTabBar, DesignerFieldList, DesignerToolbar, DesignerPageSettings,
DesignerPropertyPanel, DesignerFilterPanel, DesignerBindingEditor, DesignerInspector, DesignerSidebar
type DesignerCanvasProps, DesignerTabBarProps, DesignerFieldListProps, DesignerToolbarProps,
DesignerPageSettingsProps, DesignerPropertyPanelProps, DesignerFilterPanelProps,
DesignerBindingEditorProps, DesignerInspectorProps, DesignerSidebarProps
type TabGate // whenTab: a tab key, an array of them, or undefined (= always render)
// The 10 hooks. Five accessors (the context value as-is) and five selectors
// (derived, so a part pays only for what it reads). They throw outside a
// <DesignerProvider>, naming the provider — they never return null quietly.
useDesignerData, useDesignerActions, useDesignerSelection, useDesignerUi, useDesignerConfig
useDesignerSelectedSchema, useDesignerFieldListSchemas, useDesignerBulkEdit,
useDesignerTabWarnings, useDesignerFilterColumns
type DesignerDataValue, DesignerActionsValue, DesignerSelectionValue,
DesignerUiValue, DesignerConfigValue
// Primitive registry — swap the components the editor renders INSIDE itself
// (see "Customizing components"). 12 slots: Button, Input, ColorInput, Select,
// Textarea, Checkbox, Modal, Card, CardHeader, CardTitle, Badge, TabPanel.
UiComponentsProvider // <Designer components={...}> is sugar for this
useUiComponents() // how a part of your own resolves the current set
defaultUiComponents // ours — `{ Modal: defaultUiComponents.Modal }` to opt back in
type UiComponents, type UiComponentsOverride, type UiComponentsProviderProps
// UI language (see "UI language")
I18nProvider, useT, useLocale, withInlineCode
type Locale, type Dict
// Ready-made UI (optional — see "Ready-made UI components")
Button, Card, CardHeader, CardTitle, Badge, TabPanel, Modal, Input, ColorInput, Textarea, Select
Checkbox, PalettePicker, PaletteSwatches, MaterialIcon, CollapsibleSection, ClearFieldButton
type BadgeProps, ButtonProps, CardProps, CardTitleProps, CheckboxProps, ClearFieldButtonProps,
CollapsibleSectionProps, ColorInputProps, InputProps, MaterialIconProps, ModalProps,
PaletteGroup, PaletteGroupItem, PalettePickerProps, PaletteSwatchesProps, SelectProps,
TabPanelProps, TextareaProps
type ClassValue, LabeledParts, PartStyle // the styling API: cx's input, and any `parts` value
// The 20 icons — plain functions (no ref), props are IconProps = SVGAttributes
IconPlus, IconX, IconTrash, IconPencil, IconGrip, IconLink, IconMinus, IconArrowsHorizontal,
IconArrowsVertical, IconChevronLeft, IconChevronRight, IconDots, IconUpload, IconLock,
IconLockOpen, IconBringToFront, IconSendToBack, IconRefresh, IconDownload, IconFolderUp,
IconAlertTriangle
type IconProps
// Generation (also in json-pdf-designer/server, except downloadPdf)
generatePdf(template, data, bindings, { fontBytes?, maxPages? }) => Promise<Uint8Array>
downloadPdf(bytes, filename?) // browser-only (document/Blob) — not in /server
normalizeFontBytes(bytes) // detects WOFF/WOFF2 and decompresses
// Bindings (also in json-pdf-designer/server)
buildInputs(data, bindings) // resolves every binding at once
renderTemplate(template, data) // resolves a free "{token}" template
resolveToken(token, data) // resolves a single token/function
rowsFromArrayBinding(list, columns) // array of objects -> table rows
columnLabel(col), columnKey(col)
// Coluna de tabela: token sempre, rótulo separado da referência
tokenFor(key) => string // "id" -> "{[id]}"; a regra única
segmentFor(key) => string // o segmento sozinho: "[id]"
columnFormulaFor(content, columns, i) // a MESMA precedência que o PDF usa
makeBoundTable(nextY, path, columns, t?) // { schema, binding } já com token
normalizeTableColumns(template, bindings) // chave crua -> {label, formula}; idempotente
describeBinding(b, t?), describeBindingShort(b, t?) // t: Dict, for UI display — defaults to English
CUSTOM_FIELD_FUNCTIONS // the list of available functions (for a custom UI)
resolveChartItems(binding, data) // "chart" binding -> raw [{label, value}]
aggregateChartItems(items, topN?, sortBy?, palette?) // groups into the topN largest + "Other" (with a color)
resolveKpiValue(binding, data) // "kpi" binding -> a single aggregated number
// Chart color palettes (also in json-pdf-designer/server)
CHART_COLORS, CHART_OTHER_COLOR, CHART_PALETTES, CHART_PALETTE_LABELS,
CHART_PALETTE_NAMES, CHART_PALETTE_SIZE, resolveChartPalette, resolveChartColors
type ChartPaletteName, type ChartPresetName
// KPI icons (also in json-pdf-designer/server)
MATERIAL_ICON_GRID, MATERIAL_ICON_PATHS, MATERIAL_ICON_LABELS, MATERIAL_ICON_NAMES,
materialIconLabels(locale) // English or Portuguese icon search labels
type MaterialIconName
// Schema factories (also in json-pdf-designer/server)
makeChartSchema(nextY, t?), makeKpiSchema(nextY, t?), makeSectionColumnPair(sectionId, column, x, y, t?)
// Zones — header/footer/margin (also in json-pdf-designer/server)
classifyZone(schema, page, bands) => Zone // "header" | "footer" | "marginLeft" | "marginRight" | "body"
isRedZone(zone), clampToZone(...)
// Units (also in json-pdf-designer/server)
mmToPx, pxToMm, mmToPt
// Page — size and orientation (also in json-pdf-designer/server)
PAGE_SIZE_PRESETS // A4/A3/A5/Letter/Legal, always portrait
orientationOf(page), applyOrientation(page, orientation), matchPreset(page)
// Template format version (also in json-pdf-designer/server)
migrateTemplate(input) => Template // normalizes a template from a DB/file/API
CURRENT_TEMPLATE_VERSION // the format version this build writes
// Generation errors, as classes (all also in json-pdf-designer/server) — see Failure modes
PdfGenerationError // abstract base; nothing throws it directly
PageLimitError, PaginationStalledError // pagination: too many pages / a pass that consumed nothing
InvalidPageSizeError // width/height not two finite numbers > 0
UnsupportedGlyphError // character with no glyph in the font
Woff2SupportMissingError, FontDecompressFailedError, FontDecompressTimeoutError
ImageUploadTooLargeError, ImageUploadUnreadableError // rejected at upload
ImageTooLargeError, TooManyImagesError, UnsupportedImageFormatError
ImageUnreadableError, BackgroundImageUnreadableError
TemplateNotAnObjectError, TemplateVersionInvalidError, TemplateVersionTooNewError
TemplateMigrationMissingError // our gap between two versions
isPdfError(err) => err is AnyPdfError // narrows unknown; gives you code + blame
PDF_ERROR_CODES // the 18 codes, as a const tuple
type PdfErrorCode, PdfErrorBlame, AnyPdfError
DEFAULT_MAX_PAGES // 5000
// Turning a caught error into copy someone can read (also in json-pdf-designer/server)
describePdfError(err, dict) => PdfProblem | null // null when the error is not ours
type PdfProblem // { code, blame, title, action?, field?, detail }
type PdfProblemCode // PdfErrorCode | "expression" — 19 members
ExpressionError // base of the two below; its own hierarchy
ExpressionSyntaxError, ExpressionDepthError
// Canvas zoom - its OWN context, so only what reads it re-renders
useDesignerZoom() // { zoom, min, max, step, setZoom, zoomIn, zoomOut, reset, fitWidth, fitHeight, viewportRef }
clampZoom(n), ZOOM_MIN, ZOOM_MAX, ZOOM_STEP // the limits the canvas uses; clampZoom turns NaN into 1
type DesignerZoomValue
// <DesignerCanvas hideZoombar /> removes the default bar - see Composing the Designer
// Expression validation (also in json-pdf-designer/server) — see Conditional visibility
expressionError(source) => string | null // one expression: the syntax error, or null
templateExpressionErrors(template) // every bad {...} of a template, with its message
expressionErrors(schema, binding) // every expression a field carries
suspiciousOperator(source) // one-sided operator: valid syntax, almost certainly a typo
templateSuspiciousOperators(template) // the same, token by token
suggestAt(text, caret), applySuggestion(text, caret, s), insertAtCaret(text, caret, insert), wordAtCaret(text, caret), ALL_SUGGESTIONS
tokenAtCaret(template, caret), braceError(template, t?) // the {...} the caret is in; unbalanced brace
fieldWarning(schema, binding, t?) // the editor's alert message for a field
dictFor(locale) // a translation dictionary as a value, for the `t` above
filterIncomplete(binding)
type SchemaExpressionError
// Types (also in json-pdf-designer/server)
Template, TemplatePage, TemplateVersion, Schema, TextSchema, TableSchema, TableColumnStyle, TableCornerRadii,
ImageSchema, SectionSchema, ChartSchema, KpiSchema, KpiIcon, KpiElementKey, KpiElementOffset,
BaseSchema, PageSize, Binding, KpiAggregation, TableColumn, DataSourceOption,
SectionColumnDragPayload, Zone, Bands, GeneratePdfOptions, Orientation
json-pdf-designer/preview
A separate entry point for everything that uses pdf.js. pdfjs-dist is an
optional peer dependency (~35MB installed), so nothing reachable from the
main entry or /server imports it — only this one does. Run
npm install pdfjs-dist if you import from here.
PdfPreview // <canvas> per page, renders the generated bytes
PdfPreviewModal // a full modal around PdfPreview (download/close buttons)
configurePdfWorker(url) // self-host pdf.js's worker instead of the default CDN
That's the whole entry point — rendering the preview is the only thing the package uses pdf.js for. See Ready-made UI components.