Sayi/poi-tl — a backend project — sits at 5.2k GitHub stars in the Backend space. Generate awesome word(docx) with template
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
A better way to generate Word (.docx) documents from templates in Java, powered by Apache POI.
What is poi-tl
FreeMarker or Velocity generates HTML pages or configuration files based on text templates and data. poi-tl is a Word template engine that generates new documents based on a Word template and a data model.
The Word template provides rich styling. poi-tl perfectly preserves all fonts, colors, layouts, and alignments from your template in the generated document. You can also configure styles directly for tags in code, allowing you to focus on template design.
poi-tl is a logic-less template engine. There are no complicated control structures or variable assignments in the template—only tags. Tags can be replaced with text, pictures, tables, and lists; certain tags can conditionally show or hide document blocks, and others loop over collections.
"Powerful" constructs like variable assignment or conditional statements make it easy to modify the look of an application within the template system exclusively... however, at the cost of separation, turning the templates themselves into part of the application logic.
— Google CTemplate
poi-tl supports custom functions (plugins). Functions can execute anywhere in the Word template—Do anything anywhere in the document is the ultimate goal of poi-tl.
Feature
Description
:white_check_mark: Text
Render the tag as text
:white_check_mark: Picture
Render the tag as a picture
:white_check_mark: Table
Render the tag as a table
:white_check_mark: Numbering
Render the tag as a numbering
:white_check_mark: Chart
Bar chart (3D bar chart), column chart (3D column chart), area chart (3D area chart), line chart (3D line chart), radar chart, pie chart (3D pie Figure) and other chart rendering
:white_check_mark: If Condition
Hide or display certain document content (including text, paragraphs, pictures, tables, lists, charts, etc.) according to conditions
:white_check_mark: Foreach Loop
Loop through certain document content (including text, paragraphs, pictures, tables, lists, charts, etc.) according to the collection
:white_check_mark: Loop table row
Loop to copy a row of the rendered table
:white_check_mark: Loop table column
Loop copy and render a column of the table
:white_check_mark: Loop ordered list
Support the loop of ordered list, and support multi-level list at the same time
:white_check_mark: Highlight code
Word highlighting of code blocks, supporting 26 languages and hundreds of coloring styles
:white_check_mark: Markdown
Convert Markdown to a word document
:white_check_mark: Word attachment
Insert attachment in Word
:white_check_mark: Word Comments
Complete support comment, create comment, modify comment, etc.
:white_check_mark: Word SDT
Complete support structured document tag
:white_check_mark: Textbox
Tag support in text box
:white_check_mark: Picture replacement
Replace the original picture with another picture
:white_check_mark: bookmarks, anchors, hyperlinks
Support setting bookmarks, anchors and hyperlinks in documents
:white_check_mark: Expression Language
Fully supports SpringEL expressions and can extend more expressions: OGNL, MVEL...
:white_check_mark: Style
The template is the style, and the code can also set the style
:white_check_mark: Template nesting
The template contains sub-templates, and the sub-templates then contain sub-templates
:white_check_mark: Merge
Word merge Merge, you can also merge in the specified position
:white_check_mark: custom functions (plug-ins)
Plug-in design, execute function anywhere in the document
Reference tags directly reference native Word element handles. All native styles, colors, layouts, legends, and animations configured in Word are perfectly preserved; only the underlying data is updated.
How to set: Right-click any Chart or Picture in Word -> select Edit Alt Text (or Format Shape -> Alt Text) -> set the Title or Description to {{tag}}.
// 1. Multi-Series Charts (Bar, Column, Line, Area, Radar, Scatter)
ChartMultiSeriesRenderData chart = Charts.ofMultiSeries("Sales Trend", new String[]{"Q1", "Q2"})
.addSeries("2023", new Double[]{100.0, 150.0})
.addSeries("2024", new Double[]{120.0, 180.0})
.create();
// 2. Single-Series Charts (Pie, Doughnut)
ChartSingleSeriesRenderData pie = Charts.ofSingleSeries("Market Share", new String[]{"Product A", "Product B"})
.series("Share", new Integer[]{40, 60})
.create();
// 3. In-place Picture Replacement (retains existing dimensions and wrap style)
PictureRenderData avatar = Pictures.ofLocal("avatar.png").create();
Map<String, Object> data = new HashMap<>();
data.put("salesChart", chart);
data.put("sharePie", pie);
data.put("avatar", avatar);
XWPFTemplate.compile("report_template.docx").render(data).writeToFile("report.docx");
Configuration & SpringEL
poi-tl supports rich configurations and full Spring Expression Language (SpringEL) integration:
Iterates dynamic table columns horizontally using [] syntax.
DynamicTableRenderPolicy
poi-tl (core)
Abstract policy exposing native XWPFTable for low-level cell merging and custom table layout.
CommentRenderPolicy
poi-tl (core)
Creates Word comments: Comments.of("target").comment("note").create().
AttachmentRenderPolicy
poi-tl (core)
Embeds Excel/Word files into docx: Attachments.ofLocal("data.xlsx", AttachmentType.XLSX).create().
HighlightRenderPolicy
poi-tl-plugin-highlight
Syntax highlighting for 26+ languages with 100+ themes (zenburn, github, darcula).
MarkdownRenderPolicy
poi-tl-plugin-markdown
Directly converts Markdown strings into formatted Word documents.
Custom Plugin in 5 Lines
Implement RenderPolicy (or extend AbstractRenderPolicy<T>) to do anything anywhere in the document:
public class HelloRenderPolicy implements RenderPolicy {
@Override
public void render(ElementTemplate eleTemplate, Object data, XWPFTemplate template) {
XWPFRun run = ((RunTemplate) eleTemplate).getRun();
run.setText(String.valueOf(data), 0);
}
}
// Bind to tag {{greeting}}
Configure config = Configure.builder().bind("greeting", new HelloRenderPolicy()).build();
Compatibility & Best Practices
Version Compatibility Matrix
poi-tl Version
Apache POI Version
JDK Baseline
1.12.x / 1.13.x
5.2.2+
JDK 1.8+
1.10.x ~ 1.11.x
4.1.2 ~ 5.1.0
JDK 1.8+
1.5.x ~ 1.9.x
3.16 ~ 4.1.2
JDK 1.6+ / 1.8+
Stream Handling & Web Download
Always close resources safely using PoitlIOUtils:
response.setContentType("application/octet-stream");
response.setHeader("Content-Disposition", "attachment;filename=\"report.docx\"");
OutputStream out = response.getOutputStream();
template.write(out);
PoitlIOUtils.closeQuietlyMulti(template, out);
Common Pitfalls
NoSuchMethodError / ClassNotFoundException: Caused by dependency version collision. Ensure all transitive Apache POI dependencies are upgraded to 5.2.2+.
Tags split across multiple Runs: When editing templates in Word, spell-checking or formatting changes can split {{tag}} into multiple XML Runs. Cut and re-paste the tag as plain text, or rely on poi-tl's automatic run merge scanner.
Contributing & License
Pull requests, issue discussions, and documentation improvements are welcome!
poi-tl is open-sourced under the Apache License 2.0.
How does Sayi/poi-tl compare to other Backend projects?
Sayi/poi-tl is tracked by TopGit in the Backend category, with 5.2k GitHub stars and written in Java. Browse the Backend topic page on TopGit to compare it against similar projects by stars and activity.
How many stars does Sayi/poi-tl have?
Sayi/poi-tl has 5.2k GitHub stars — refresh the page for the live number, or check github.com/Sayi/poi-tl. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
Is Sayi/poi-tl open source?
Yes — Sayi/poi-tl ships under the Apache-2.0 license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/Sayi/poi-tl.
What else is in the Backend space?
Sayi/poi-tl is tracked by TopGit under the Backend category, alongside 7 GitHub-tagged topics. Trending and Topics pages list peer repositories of comparable stars and language.
What is Sayi/poi-tl?
Sayi/poi-tl (Sayi/poi-tl) is a Java project on GitHub. From the project's own README: Generate awesome word(docx) with template
Where can I see Sayi/poi-tl in action?
The project maintains a homepage at https://deepoove.com/poi-tl/. The README tab on this page also usually contains screenshots and a quickstart.
Where do I read more about Sayi/poi-tl?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/Sayi/poi-tl is the definitive source.
Read full README in the tab above.
Is poi-tl worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of poi-tl.