visualpdf 1.0.0

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

VisualPDF

[VisualPDF report builder]

VisualPDF is a visual PDF report designer and a read-only report runtime for Flutter desktop applications. 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 designer

[VisualPDF Studio invoice designer]

Highlights

• Visual A4 canvas with drag, resize, grid, and element properties.
• 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.
• 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 is desktop-first and currently declares support for:

• Linux
• macOS
• Windows

The editor needs a reasonably wide window. The rendering model itself is pure Dart/Flutter apart from file selection and native 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

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.

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": 3,
    "name": "Invoice",
    "page": {
      "format": "A4",
      "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
• API reference
• Complete example

Current scope

• The visual canvas currently uses A4 portrait pages.
• The renderer currently creates one physical PDF page per template.
• Built-in PDF fonts are Helvetica, Times, and Courier.
• User-provided TTF/OTF font embedding and automatic table pagination are planned extensions.

Support

Questions and feedback: Martin Bundschuh

License

VisualPDF is available under the MIT License.