The following is meant to serve as a handy reference for the most essential XSL-FO elements, the components used to create structured and precise layouts in XML-based formatting. XSL-FO (Extensible Stylesheet Language Formatting Objects) is a specialized language for transforming XML data into print-ready formats such as PDF, commonly used for creating books, reports, and other professionally formatted documents.
Whether you're just starting with XSL-FO or refining your knowledge, this quick reference is designed for anyone working with XML content that requires specific page layout control. Below, you'll find tables detailing the most commonly used page structure and inline structure elements, followed by a breakdown of more specialized components, along with their descriptions and attributes.
Elements MatrixThe following matrix seeks to list all important xsf-fo elements and considers their most common use scenarios.
We have separated them in two categories: structural elements (like pages, regions, blocks, tables) and more "inline" elements (elements that make up or build other structures, like table-rows, etc. ).
Most common elements
| Page Structure Elements | Inline Structure Elements | Attributes | Description | Where It Occurs | Special Features |
|---|---|---|---|---|---|
<fo:root> | xmlns:fo | The root element of the XSL-FO document, contains the page layout and content sequences. | Top-level element. | Contains <fo:layout-master-set> and <fo:page-sequence>. | |
<fo:layout-master-set> | N/A | Defines the page layouts used by the content. | Inside <fo:root>. | Contains multiple page masters, like <fo:simple-page-master>. | |
<fo:simple-page-master> | master-name, page-height, page-width, margin, margin-top, margin-bottom, margin-left, margin-right | Defines the layout for a specific page, including size and regions. | Inside <fo:layout-master-set>. | Defines regions such as <fo:region-body>, <fo:region-before>, and <fo:region-after>. | |
<fo:page-sequence> | master-reference | Container for content rendered on pages, references the page layout defined earlier. | Inside <fo:root>. | Contains both flowing content (<fo:flow>) and static content (<fo:static-content>). | |
<fo:region-body> | margin, column-count, column-gap, margin-top, margin-bottom | Defines the main content area of the page. | Inside <fo:simple-page-master>. | Can be multi-column using column-count and column-gap. | |
<fo:region-before> | extent, background-color | Defines the header area of a page. | Inside <fo:simple-page-master>. | extent determines the size of the header region. | |
<fo:region-after> | extent, background-color | Defines the footer area of a page. | Inside <fo:simple-page-master>. | Frequently used for page numbers or footer content. | |
<fo:conditional-page-master-reference> | master-reference, odd-or-even, page-position | Selects different page masters based on conditions (e.g., odd/even, first page). | Inside <fo:page-sequence-master>. | Helps create alternating layouts for odd/even pages. | |
<fo:flow> | flow-name | Contains the main flowing content, typically into the body of the page. | Inside <fo:page-sequence>. | Must refer to xsl-region-body. | |
<fo:static-content> | flow-name | Defines static content (e.g., headers or footers) that is repeated on every page. | Inside <fo:page-sequence>. | Typically used for headers and footers, referencing regions like xsl-region-before and xsl-region-after. | |
<fo:block> | font-family, font-size, text-align, space-before, space-after, margin, background-color, color | A container for block-level content such as paragraphs and headings. | Inside <fo:flow> or <fo:table-cell>. | Supports multiple styling attributes for text layout. | |
<fo:table> | table-layout, width, border, space-before | Defines a table, useful for organizing content in rows and columns. | Inside <fo:flow>. | Often used to create structured, tabular layouts or multi-column content. | |
<fo:repeatable-page-master-alternatives> | N/A | Allows defining different page layouts for different situations (e.g., odd/even, first page). | Inside <fo:page-sequence-master>. | Provides flexibility for applying different page layouts in various scenarios. | |
<fo:bookmark-tree> | N/A | Defines the structure of bookmarks for navigation in PDFs. | Inside <fo:page-sequence>. | Can contain multiple <fo:bookmark> elements. | |
<fo:bookmark> | internal-destination | Represents a single bookmark that links to a specific part of the document. | Inside <fo:bookmark-tree>. | Creates a clickable link for navigation within the document. | |
<fo:page-sequence-master> | master-name | Defines multiple page layouts, like a sequence of pages for odd/even. | Inside <fo:layout-master-set>. | Allows for complex layout control, switching between different page masters. | |
<fo:retrieve-marker> | retrieve-position, retrieve-boundary | Retrieves markers, typically used in headers or footers. | Inside <fo:static-content>. | Useful for dynamic content generation, such as running headers. | |
<fo:marker> | marker-class-name | Defines content that can be retrieved and inserted elsewhere in the document. | Inside <fo:flow>. | Frequently used to mark content that can be reused in headers or footers. | |
<fo:page-number> | N/A | Inserts the current page number. | Inside <fo:static-content>. | Automatically increments for each page. | |
<fo:inline> | font-family, font-size, color, text-decoration | Inline styling for text. | Inside <fo:block>, <fo:table-cell>. | Allows applying specific styles to portions of a block-level element. | |
<fo:table-column> | column-width | Defines the width of a table column. | Inside <fo:table>. | Can be used to set the width for multiple columns in a table. | |
<fo:table-row> | N/A | Represents a row of table cells. | Inside <fo:table-body>. | Contains multiple <fo:table-cell> elements. | |
<fo:table-cell> | padding, border, background-color, font-size | Defines a cell within a table. | Inside <fo:table-row>. | Can contain both block and inline-level content and be styled individually. | |
<fo:leader> | leader-pattern, leader-length | Generates dots, dashes, or spaces, commonly used for aligning items like a TOC. | Inside <fo:block>. | Creates filler content like dotted lines between entries and their page numbers. | |
<fo:basic-link> | internal-destination, external-destination, color, text-decoration | Creates a link either within the document or to an external destination. | Inside <fo:block>, <fo:inline>. | Adds navigable links within the document or to an external website. | |
<fo:page-number-citation> | ref-id | References the page number of another element, often used in a table of contents. | Inside <fo:block>, <fo:inline>. | Displays the page number where a specific referenced item appears in the document. |
Less Commonly Used Elements
| Page Structure Elements | Inline Structure Elements | Attributes | Description | Where It Occurs | Special Features |
|---|---|---|---|---|---|
<fo:multi-switch> | N/A | A container for alternate content, allowing switching between different content based on conditions. | Inside <fo:flow>. | Can switch between multiple content options, typically used for interactive or dynamic content. | |
<fo:multi-case> | id, media-usage, space-before, space-after | Defines one of the alternative content containers for <fo:multi-switch>. | Inside <fo:multi-switch>. | Can contain flow content to be used based on conditions or usage scenarios. | |
<fo:page-number-citation-last> | ref-id | Similar to <fo:page-number-citation>, but refers to the last page where an element occurs. | Inside <fo:block>, <fo:inline>. | Displays the last page number that an element spans, often used for chapters or sections. | |
<fo:float> | float, clear, width, height, border, padding, background-color | Allows block content to be floated alongside other content, such as sidebars or images. | Inside <fo:flow>. | Supports positioning elements next to the main content flow, much like floating images in HTML. | |
<fo:footnote> | N/A | Defines a footnote in the document, including both the reference and the footnote content. | Inside <fo:block>. | Contains <fo:footnote-body> and automatically places the footnote content in the region-after area. | |
<fo:footnote-body> | N/A | The content of a footnote that is referenced by the <fo:footnote> element. | Inside <fo:footnote>. | Automatically positioned at the bottom of the page where the footnote is referenced. | |
<fo:marker> | marker-class-name | Defines a marker for content that can be retrieved and displayed elsewhere, such as headers and footers. | Inside <fo:flow>. | Useful for inserting dynamic content like running headers, which update based on the chapter or section. | |
<fo:retrieve-table-marker> | retrieve-class-name, retrieve-boundary, retrieve-position | Retrieves table-specific markers, used for headers and footers of multi-page tables. | Inside <fo:table-header>, <fo:table-footer>. | Ensures headers and footers of tables are correctly positioned across multi-page table spans. | |
<fo:index-page-citation-list> | index-key | Represents a list of page citations for an index entry, used for creating an index of terms in the document. | Inside <fo:index-page-sequence>. | Allows creating an index with references to page numbers for specific terms. | |
<fo:index-page-sequence> | master-reference, index-key | A page sequence dedicated to rendering an index of terms in the document. | Inside <fo:root>. | Used for creating a structured index at the end of the document. | |
<fo:index-range-begin> | index-key | Marks the beginning of a page range for an index entry, to be used with <fo:index-range-end>. | Inside <fo:flow>. | Commonly used in indexes to define page ranges for terms that span multiple pages. | |
<fo:index-range-end> | index-key | Marks the end of a page range for an index entry, closing the range opened by <fo:index-range-begin>. | Inside <fo:flow>. | Allows defining a start and end for page ranges of index entries. | |
<fo:wrapper> | N/A | A generic container element, often used to apply styles to a group of child elements without introducing structure. | Inside <fo:flow>. | Does not introduce a block-level or inline structure but allows grouping for styling purposes. | |
<fo:leader> | leader-pattern, leader-length, leader-alignment | Creates a visual leader (e.g., dots or dashes) used in tables of contents or aligned columns of text. | Inside <fo:block>. | Used to fill space with a visual pattern between two elements, such as chapter titles and page numbers in a TOC. | |
<fo:basic-link> | external-destination, internal-destination, color, text-decoration | Defines a clickable link, either internal (within the document) or external (to a website). | Inside <fo:block>, <fo:inline>. | Used to create hyperlinks in the output PDF or other rendered formats. | |
<fo:instream-foreign-object> | width, height, content-type, src | Embeds external content, such as images or multimedia, directly in the flow of the document. | Inside <fo:block>, <fo:inline>. | Allows embedding SVG images, video, or other media types. | |
<fo:bidi-override> | unicode-bidi, direction | Overrides the bidirectional (bidi) text algorithm, often used for languages written from right to left. | Inside <fo:inline>. | Useful for handling content that mixes left-to-right and right-to-left languages, like English and Arabic. | |
<fo:external-graphic> | src, width, height, scaling, content-width, content-height | Embeds an external image into the document, such as a logo or diagram. | Inside <fo:block>, <fo:inline>. | Supports image embedding with scaling and positioning controls. | |
<fo:instream-foreign-object> | width, height, content-type, src | Embeds non-XSL-FO content like SVG graphics or multimedia objects directly into the flow. | Inside <fo:block>, <fo:inline>. | Supports embedding foreign XML namespaces and graphics such as SVG. | |
<fo:multi-toggle> | id, state, media-usage, space-before, space-after | Defines content that can toggle between visible states, often used for interactive content. | Inside <fo:multi-switch>. | Used to create interactive PDFs with content that can be expanded or collapsed. | |
<fo:page-number-citation-last> | ref-id | Displays the last page number where a referenced element occurs. | Inside <fo:inline>. | Useful for indicating ranges of pages in documents, such as "Chapter spans pages 3-15". | |
<fo:declarations> | Contains font declarations or other resources for the layout. | id | |||
<fo:region-start> | Defines the start region for side margins (left or right depending on the page). | extent, precedence, region-name | |||
<fo:region-end> | Defines the end region for side margins (opposite of region-start). | extent, precedence, region-name | |||
<fo:multi-properties> | Specifies multiple properties for formatting that can be toggled in content. | id, space-before.optimum, space-after.optimum, keep-together.within-line | |||
<fo:multi-toggle> | <fo:multi-toggle> | Allows switching between multiple layout alternatives based on certain conditions. | id, keep-with-next, keep-with-previous, break-before, break-after | Used within multi-case to toggle layout between multiple elements. | |
<fo:repeatable-page-master-alternatives> | Repeats the page masters for conditions like odd/even page layouts. | id, maximum-repeats, page-position | |||
<fo:table-and-caption> | Groups a table with a caption that appears either before or after the table. | id, caption-side | |||
<fo:table-caption> | Defines the caption for a table. | id, caption-side | |||
<fo:change-bar-begin> | Marks the beginning of a change bar, indicating modified content in a document. | id, change-bar-class, change-bar-offset, change-bar-width | |||
<fo:change-bar-end> | Marks the end of a change bar for modified content. | id, change-bar-class | |||
<fo:page-sequence-wrapper> | Wraps multiple page sequences, enabling control over page sequences. | id, initial-page-number, force-page-count, format, language, country | |||
<fo:subsequence-specifier> | Specifies subsequences in complex layouts for page sequences. | id, initial-page-number, format, force-page-count, language, country | |||
<fo:table-footer> | Defines the footer row for tables (repeated on each page in paginated tables). | id, table-layout, border-collapse, background-color, padding | |||
<fo:table-header> | Defines the header row for tables (repeated on each page in paginated tables). | id, table-layout, border-collapse, background-color, padding | |||
<fo:float> | Defines content that "floats" in the document, like images or sidebars. | id, float, clear, keep-together, keep-with-next, break-before, width | |||
<fo:footnote-reference> | Refers to a footnote in the body text and automatically links to the footnote. | id, alignment-baseline, baseline-shift, line-height, keep-with-next | |||
<fo:character> | Represents an individual character with specific styling (like vertical shifts). | ||||
<fo:inline-container> | Allows embedding of inline containers within flow content. | ||||
<fo:external-destination> | Creates external hyperlinks to URLs or files. | ||||
<fo:instream-foreign-object> | Allows embedding of foreign objects such as images or multimedia elements. | ||||
<fo:bidi-override> | Allows for overriding bidirectional text display for languages such as Arabic or Hebrew. | ||||
<fo:external-graphic> | Embeds external images, typically used for embedding logos, pictures, or illustrations. | ||||
<fo:space> | Inserts space between inline elements, can be controlled to adjust document flow. |
XSL-FO offers powerful tools for crafting print layouts from structured XML content. This reference guide provides an overview of key elements and attributes that can help you control everything from page structures to detailed inline content formatting. By familiarizing yourself with these elements, you can streamline the process of generating high-quality, print-ready documents.
