docs_gee 1.5.0

Pure Dart library for generating and reading DOCX and PDF documents with rich formatting, tables, lists. Cross-platform with no native dependencies.

docs_gee

A pure Dart library for generating Microsoft Word (DOCX) and PDF documents. Create professional documents programmatically with rich formatting, tables, lists, and more - all from a single document model. Created and supported by Codigee.

If you find this package useful, please consider giving it a star on GitHub and a like on pub.dev. It helps the package grow and stay maintained!

Documentation

Full hosted documentation is available at codigee.com/open-source/docs-gee:

• Overview - what docs_gee is and why to use it
• Document building guide - step-by-step guide to building DOCX and PDF documents
• DocxReader & API reference - full API reference and DocxReader docs (markdown source)

Why docs_gee?

• Pure Dart - No native dependencies, works everywhere Dart runs
• Dual Format - Generate both DOCX and PDF from the same document model
• Cross-Platform - iOS, Android, Web, macOS, Windows, Linux
• Lightweight - Only one dependency (archive for ZIP)
• Simple API - Intuitive document builder pattern

Features

Feature	DOCX	PDF
Text formatting (bold, italic, underline, strikethrough)	✅	✅
Superscript & subscript	✅	✅
Text colors & highlighting	✅	✅
Headings (H1-H4)	✅	✅
Paragraph styles (subtitle, caption, quote, code, footnote)	✅	✅
Text alignment (left, center, right, justify)	✅	✅
Bullet & numbered lists	✅	✅
Nested lists (up to 9 levels)	✅	✅
Tables with borders & colors	✅	✅
Per-cell border control	✅	✅
Configurable cell padding	✅	✅
Font size per run	✅	✅
Images (PNG / JPEG)	✅	-
Headers & footers	✅	-
Page numbers (PAGE / NUMPAGES fields)	✅	-
Right-to-left text (Arabic, Hebrew, Persian)	✅	-
Page breaks	✅	✅
Line breaks (soft return)	✅	-
Hyperlinks (external URLs)	✅	-
Internal links (bookmarks)	✅	-
Table of Contents	✅	-
Document metadata	✅	✅
Custom fonts	✅	✅
Extended characters (German, French)	✅	✅
Polish characters	✅	Partial*
Emoji support	✅	-

*PDF supports Ó/ó natively; other Polish characters (ą, ę, ć, etc.) fall back to ASCII equivalents due to font encoding limitations.

Installation

dependencies:
  docs_gee: ^1.3.3

dart pub add docs_gee
# or
flutter pub add docs_gee

Quick Start

import 'dart:io';
import 'package:docs_gee/docs_gee.dart';

void main() {
  // Create document
  final doc = Document(title: 'My Report', author: 'John Doe');

  // Add content
  doc.addParagraph(Paragraph.heading('Quarterly Report', level: 1));
  doc.addParagraph(Paragraph.text('This report summarizes Q4 performance.'));

  // Add a table
  doc.addTable(Table(
    rows: [
      TableRow(cells: [
        TableCell.text('Metric', backgroundColor: 'E0E0E0'),
        TableCell.text('Value', backgroundColor: 'E0E0E0'),
      ]),
      TableRow(cells: [
        TableCell.text('Revenue'),
        TableCell.text('\$1.2M', alignment: Alignment.right),
      ]),
    ],
  ));

  // Generate both formats
  File('report.docx').writeAsBytesSync(DocxGenerator().generate(doc));
  File('report.pdf').writeAsBytesSync(PdfGenerator().generate(doc));
}

Usage Examples

Rich Text Formatting

doc.addParagraph(Paragraph(
  runs: [
    TextRun('Normal, '),
    TextRun('bold, ', bold: true),
    TextRun('italic, ', italic: true),
    TextRun('colored', color: 'FF0000'),
  ],
));

Superscript & Subscript

Use script on a run to raise or lower text off the baseline — handy for exponents, ordinals, footnote markers and chemical formulas.

// E = mc²
doc.addParagraph(Paragraph(runs: [
  TextRun('E = mc'),
  TextRun('2', script: Script.superscript),
]));

// H₂O
doc.addParagraph(Paragraph(runs: [
  TextRun('H'),
  TextRun('2', script: Script.subscript),
  TextRun('O'),
]));

Lists

// Bullet list
doc.addParagraph(Paragraph.bulletItem('First item'));
doc.addParagraph(Paragraph.bulletItem('Second item'));

// Numbered list
doc.addParagraph(Paragraph.numberedItem('Step one'));
doc.addParagraph(Paragraph.numberedItem('Step two'));

// Nested list
doc.addParagraph(Paragraph.bulletItem('Parent'));
doc.addParagraph(Paragraph.bulletItem('Child', indentLevel: 1));

Tables

doc.addTable(Table(
  borders: TableBorders.all(),
  rows: [
    TableRow(cells: [
      TableCell.text('Name', backgroundColor: 'CCCCCC'),
      TableCell.text('Score', backgroundColor: 'CCCCCC'),
    ]),
    TableRow(cells: [
      TableCell.text('Alice'),
      TableCell.text('95', alignment: Alignment.right),
    ]),
  ],
));

Cell Borders

Override table-level borders on individual cells:

doc.addTable(Table(
  borders: const TableBorders.all(),
  rows: [
    TableRow(cells: [
      // Cell with custom red borders
      TableCell.text('Alert', borders: const CellBorders.all(color: 'FF0000', size: 8)),
      TableCell.text('Normal cell'),
    ]),
    TableRow(cells: [
      // Cell with only bottom border
      TableCell.text('Underlined', borders: const CellBorders.bottom()),
      // Cell with no borders (overrides table borders)
      TableCell.text('Clean', borders: const CellBorders.none()),
    ]),
  ],
));

// Selective sides with different styles
TableCell(
  paragraphs: [Paragraph.text('Custom')],
  borders: const CellBorders(
    top: Border(color: 'FF0000', size: 8, style: BorderStyle.double),
    bottom: Border(color: '0000FF'),
  ),
);

Images (DOCX only)

The intrinsic size is read from the PNG or JPEG header, so a picture needs no explicit dimensions:

final doc = DocxDocument();
doc.addImage(DocxImage(
  bytes: pngBytes,
  altText: 'Quarterly revenue chart',
));

// Scaled to 400px wide, height derived from the aspect ratio
doc.addImage(DocxImage(
  bytes: jpegBytes,
  width: 400,
  alignment: DocxAlignment.center,
));

Anything that is not PNG or JPEG, or whose header is truncated, throws DocxImageException rather than producing a document Word cannot open.

Headers, Footers and Page Numbers (DOCX only)

final doc = DocxDocument(
  header: DocxHeaderFooter.text(
    'Quarterly report',
    alignment: DocxAlignment.center,
  ),
  // Renders "Page 3 of 12", recalculated by the word processor on open
  footer: DocxHeaderFooter.pageNumber(prefix: 'Page ', showTotal: true),
);

Build a richer one from paragraphs, and place the page number yourself with the field runs:

DocxHeaderFooter(paragraphs: [
  DocxParagraph(
    runs: [
      const DocxRun('Confidential', italic: true),
      const DocxRun('  -  '),
      const DocxRun.pageNumber(bold: true),
    ],
    alignment: DocxAlignment.right,
  ),
]);

External hyperlinks inside a header or footer render as plain text: those parts resolve relationship ids against their own relationship file, which this library does not emit.

Right-to-Left Text (DOCX only)

doc.addParagraph(const DocxParagraph(
  runs: [DocxRun('مرحبا بالعالم', rtl: true)],
  rtl: true,
));

rtl on the paragraph flips the paragraph direction (<w:bidi/>); rtl on the run marks the text itself as right-to-left (<w:rtl/>). Set both for Arabic, Hebrew or Persian content. The PDF generator has no bidirectional text shaping and renders such content left-to-right.

Font Size per Run

doc.addParagraph(const DocxParagraph(runs: [
  DocxRun('Lead-in ', fontSize: 18),
  DocxRun('and the rest at the document default.'),
]));

Sizes are in points and apply to DOCX and PDF alike; in PDF the line grows to fit the tallest run on it.

Table Cell Padding

// Table-wide
DocxTable.simple(
  [['Product', 'Price']],
  cellPadding: const DocxCellPadding.points(top: 6, bottom: 6, left: 10, right: 10),
);

// Per cell, overriding the table default
DocxTableCell.text('Roomy', padding: const DocxCellPadding.all(200));

Padding is stored in twips (1/1440 inch); DocxCellPadding.points(...) converts from points and DocxCellPadding.wordDefault matches Word's own margins.

Semantic Styles

doc.addParagraph(Paragraph.heading('Title', level: 1));
doc.addParagraph(Paragraph.subtitle('Document subtitle'));
doc.addParagraph(Paragraph.quote('A famous quote...'));
doc.addParagraph(Paragraph.codeBlock('const x = 42;'));
doc.addParagraph(Paragraph.caption('Figure 1: Chart'));

Page Breaks

doc.addParagraph(Paragraph.heading(
  'New Chapter',
  level: 1,
  pageBreakBefore: true,
));

Line Breaks (Soft Return) - DOCX only

Line breaks allow multiple lines within a single paragraph (like Shift+Enter in Word).

// Using \n in text (automatic conversion)
doc.addParagraph(Paragraph.text('Line 1\nLine 2\nLine 3'));

// Using explicit line break runs (for different formatting per line)
doc.addParagraph(Paragraph(
  runs: [
    TextRun('Bold line', bold: true),
    TextRun.lineBreak(),
    TextRun('Normal line'),
    TextRun.lineBreak(),
    TextRun('Italic line', italic: true),
  ],
));

Hyperlinks

// External link
doc.addParagraph(Paragraph(
  runs: [
    TextRun('Visit '),
    TextRun('our website', hyperlink: 'https://example.com'),
    TextRun(' for more info.'),
  ],
));

Internal Links (Bookmarks)

// Create a bookmark
doc.addParagraph(Paragraph.heading(
  'Chapter 1: Introduction',
  level: 1,
  bookmarkName: 'chapter1',
));

// Link to the bookmark
doc.addParagraph(Paragraph(
  runs: [
    TextRun('Go to '),
    TextRun('Chapter 1', bookmarkRef: 'chapter1'),
  ],
));

Table of Contents

// Enable automatic Table of Contents
final doc = Document(
  title: 'My Document',
  includeTableOfContents: true,
  tocTitle: 'Contents',
  tocMaxLevel: 3,  // Include Heading 1-3
);

doc.addParagraph(Paragraph.heading('Introduction', level: 1));
doc.addParagraph(Paragraph.heading('Getting Started', level: 2));
// TOC will be auto-generated with links to these headings

Platform Support

Platform	Support
Android	✅
iOS	✅
Web	✅
macOS	✅
Windows	✅
Linux	✅

Web Usage

import 'dart:html' as html;

void downloadDocument(Uint8List bytes, String filename) {
  final blob = html.Blob([bytes]);
  final url = html.Url.createObjectUrlFromBlob(blob);
  html.AnchorElement(href: url)
    ..setAttribute('download', filename)
    ..click();
  html.Url.revokeObjectUrl(url);
}

Mobile Usage

import 'package:path_provider/path_provider.dart';
import 'package:share_plus/share_plus.dart';

Future<void> shareDocument(Uint8List bytes) async {
  final dir = await getTemporaryDirectory();
  final file = File('${dir.path}/document.docx');
  await file.writeAsBytes(bytes);
  await Share.shareXFiles([XFile(file.path)]);
}

API Reference

Main Classes

Class	Description
Document / DocxDocument	Document container with metadata
Paragraph / DocxParagraph	Paragraph with text runs and styling
TextRun / DocxRun	Text segment with formatting
Table / DocxTable	Table with rows and borders
TableRow / DocxTableRow	Table row with cells
TableCell / DocxTableCell	Table cell with content
DocxGenerator	Generates DOCX bytes
PdfGenerator	Generates PDF bytes

Paragraph Styles

Style	Method
Normal text	Paragraph.text('...')
Heading 1-4	Paragraph.heading('...', level: 1)
Subtitle	Paragraph.subtitle('...')
Caption	Paragraph.caption('...')
Quote	Paragraph.quote('...')
Code block	Paragraph.codeBlock('...')
Footnote	Paragraph.footnote('...')
Bullet list	Paragraph.bulletItem('...')
Dash list	Paragraph.dashItem('...')
Numbered list	Paragraph.numberedItem('...')
Alpha list	Paragraph.alphaItem('...')
Roman list	Paragraph.romanItem('...')

Text Formatting

Property	Type	Description
bold	bool	Bold text
italic	bool	Italic text
underline	bool	Underlined text
strikethrough	bool	Strikethrough text
color	String	Hex color (e.g., 'FF0000')
backgroundColor	String	Highlight color
script	DocxScript	Superscript / subscript (Script.superscript, Script.subscript)
hyperlink	String?	External URL link
bookmarkRef	String?	Internal bookmark reference
isLineBreak	bool	Line break (use TextRun.lineBreak())
fontSize	int?	Font size in points, overriding the document default
rtl	bool	Right-to-left run direction (DOCX only)
field	DocxField?	Page field (use DocxRun.pageNumber() / .pageCount())

Compatibility

Generated documents are compatible with:

• Microsoft Word 2007+
• Google Docs
• LibreOffice Writer
• Apple Pages
• WPS Office
• Any OOXML-compatible application

Requirements

• Dart SDK: >=3.0.0 <4.0.0
• Flutter: >=3.0.0 (if using with Flutter)

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests on GitHub.

License

MIT License - see LICENSE for details.

---

Made with ❤️ by Codigee