visualpdf 1.8.5

A visual Flutter PDF report designer and runtime for JSON-driven invoices, templates, tables, barcodes, headers, footers, and printing.

VisualPDF

VisualPDF is a visual PDF report designer and a read-only report runtime for Flutter applications on Android, iOS, Linux, macOS, Web, and Windows. Design invoices and reports at runtime, bind elements to JSON data, save the layout as a portable .vps template, and render or print the final PDF with a separate data file.

The package deliberately keeps layout and business data separate:

report.vps + invoice.json -> PDF preview -> print / export

This makes it possible to let an administrator design a template once while end users only execute and print it.

Visual tour

VisualPDF Studio

From visual template to PDF

Highlights

• Visual A5, A4, A3, and A2 canvas in portrait or landscape orientation, with drag, resize, grid, and element properties.
• Responsive touch UI with mobile drawers and pinch-to-zoom canvas.
• Two application modes: full editor and protected runtime.
• Text and multiline JSON-bound fields.
• Left, center, and right text alignment.
• Helvetica, Times, and Courier PDF fonts with normal and bold styles.
• Configurable print colors for text, fields, shapes, lines, tables, and codes.
• Horizontal and vertical lines with adjustable length and thickness.
• Tables generated from JSON arrays.
• Automatic table pagination with repeated column headers.
• Per-column headers, widths, number/currency formats, and alignment.
• SUM, COUNT, AVERAGE, MIN, and MAX table functions.
• Optional subtotals, discounts, multiple tax rates, and grand totals.
• Results can be placed in the calculated table column.
• PNG, JPEG, and WebP images embedded directly into the template.
• QR, EAN-13, and EAN-8 codes with JSON data binding.
• Adjustable header and footer regions.
• PageNumber, PageCount, Date, Time, and DateTime system fields.
• Portable, human-readable .vps JSON envelope.
• Native PDF preview, export, sharing, and printing through printing.

Supported platforms

VisualPDF currently declares support for:

• Android
• iOS
• Linux
• macOS
• Web
• Windows

The runtime is optimized for phones, tablets, and desktop windows. On compact screens the editor places elements and properties in slide-out drawers and fits the selected document canvas to the available space. Pinch to zoom and drag to pan while editing on touch devices.

On Android, iOS, and desktop, the native document picker opens .vps templates and JSON files. On Web, the browser file picker handles uploads and generated VPS, JSON, and PDF files can be downloaded. PDF preview and the available platform print/share workflow are provided through printing.

Installation

Add the package:

flutter pub add visualpdf

Import its public API:

import 'package:visualpdf/visualpdf.dart';

Quick start: print-only runtime

VisualPdfRuntime is the recommended production surface. It has no template editing controls and accepts the template and report data as strings.

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:visualpdf/visualpdf.dart';

void main() {
  final template = ReportTemplate(
    name: 'Invoice',
    elements: [
      ReportElement(
        id: 'title',
        type: ElementType.text,
        x: 42,
        y: 42,
        width: 300,
        height: 40,
        value: 'INVOICE',
        fontSize: 26,
        bold: true,
        band: 'header',
      ),
      ReportElement(
        id: 'number',
        type: ElementType.field,
        x: 380,
        y: 50,
        width: 170,
        height: 24,
        value: 'No. {{invoice.number}}',
        textAlign: 'right',
        band: 'header',
      ),
    ],
  );

  final data = {
    'invoice': {'number': 'INV-2026-001'},
  };

  runApp(
    MaterialApp(
      home: VisualPdfRuntime(
        initialVps: template.toVps(),
        initialJson: jsonEncode(data),
      ),
    ),
  );
}

Set autoPrint: true to open the native print dialog after the report has loaded successfully.

Launch the complete editor

To use VisualPDF as the root application:

void main() {
  runApp(
    const VisualPdfApp(mode: VisualPdfMode.editor),
  );
}

The bundled desktop application starts in editor mode by default:

flutter run -d macos

Choose A5, A4, A3, or A2 and portrait or landscape orientation in the page properties. The same settings are available through the public template API:

final template = ReportTemplate(
  name: 'Landscape report',
  paperSize: ReportPaperSize.a3,
  orientation: ReportOrientation.landscape,
);

Page dimensions, draggable element bounds, header and footer regions, table pagination, and the generated PDF automatically follow the selected layout.

Start the same application in protected runtime mode:

flutter run -d macos --dart-entrypoint-args=--runtime

Development and automation calls can provide input paths:

flutter run -d macos \
  --dart-entrypoint-args=--runtime \
  --dart-entrypoint-args=--template=/path/invoice.vps \
  --dart-entrypoint-args=--data=/path/invoice.json \
  --dart-entrypoint-args=--auto-print

For signed sandboxed macOS apps, use initialVps/initialJson or the runtime file pickers. Arbitrary command-line paths do not automatically receive a macOS security-scoped file permission.

JSON data binding

Use double braces in text, field, QR, and EAN content:

Invoice {{invoice.number}}
{{customer.name}}
{{customer.address.city}}

With this data:

{
  "invoice": {
    "number": "INV-2026-001"
  },
  "customer": {
    "name": "Example GmbH",
    "address": {
      "city": "Munich"
    }
  }
}

VisualPDF discovers scalar fields and arrays automatically when the test JSON is changed in the editor.

Tables and calculations

A table points to a JSON array such as items. Each column selects a field in an array row.

{
  "items": [
    {
      "description": "Consulting",
      "quantity": 2,
      "price": 95,
      "total": 190,
      "taxRate": 19
    }
  ]
}

Expressions support a single field or multiplication:

total
quantity * price

Available aggregate functions are SUM, COUNT, AVERAGE, MIN, and MAX. Taxes are optional and can be filtered by a row field, which allows separate tax lines such as 7% and 19% VAT.

100-item pagination demo

The package contains a matching template/data pair:

• example/100_items.vps
• example/100_items.json

Open the VPS template in the editor, load the JSON file as test data, and select PDF erzeugen. The 100 rows are distributed over several physical A4 pages. The table header, document header, and footer repeat automatically; PageNumber and PageCount show the real page values. Totals and the mixed 7%/19% tax calculation appear only on the final page.

Applications can check the expected page count before rendering:

final pages = calculateReportPageCount(template, data);

System fields

The following tokens are resolved while rendering:

Token	Result
{{PageNumber}}	Current page number
{{PageCount}}	Total number of pages
{{Date}}	Current local date
{{Time}}	Current local time
{{DateTime}}	Current local date and time

System fields can be placed in the header, body, or footer.

Render without the runtime UI

Use the renderer directly when your application owns the preview or storage workflow:

final template = ReportTemplate.fromVps(vpsSource);
final data = jsonDecode(jsonSource) as Map<String, dynamic>;
final Uint8List bytes = await renderPdf(template, data);

The returned bytes can be stored, uploaded, attached to an email, or passed to another printing workflow.

VPS template format

VPS stands for VisualPDF Studio. A .vps file is a versioned JSON envelope that contains page settings and report elements:

{
  "format": "visualpdf-studio-template",
  "formatVersion": 1,
  "template": {
    "schemaVersion": 4,
    "name": "Invoice",
    "page": {
      "format": "A4",
      "orientation": "portrait",
      "width": 595.28,
      "height": 841.89,
      "unit": "pt",
      "headerHeight": 72,
      "footerHeight": 55
    },
    "elements": []
  }
}

Images are stored as Base64 in the template, making a VPS file self-contained. Treat templates from unknown sources as untrusted input and apply suitable file size limits in your application.

macOS entitlements

A sandboxed macOS host app needs printing and user-selected read/write access:

<key>com.apple.security.print</key>
<true/>
<key>com.apple.security.files.user-selected.read-write</key>
<true/>

Add these keys to both DebugProfile.entitlements and Release.entitlements. Restart the application completely after changing entitlements; hot reload cannot update the signed permissions.

More documentation

• Getting started
• Editor and runtime modes
• Data binding and tables
• VPS template format
• macOS integration
• Android and iOS
• Web
• API reference
• Complete example

Current scope

• The visual canvas and PDF renderer support A5, A4, A3, and A2 pages in portrait and landscape orientation.
• Built-in PDF fonts are Helvetica, Times, and Courier.
• The first JSON-backed table is the flowing table when a report needs multiple pages. Additional independently flowing tables are a planned extension.
• User-provided TTF/OTF font embedding is a planned extension.

Support

Questions and feedback: Martin Bundschuh

License

VisualPDF is available under the MIT License.