DOCSEARCHbyAlgolia
Submit Docs

docx-preview Documentation

repository·master·Indexed 24 days ago

https://github.com/volodymyrbaydalka/docxjs

A library (version 0.4.0) designed to render or convert DOCX documents into semantic HTML. It provides the renderAsync method to convert Blobs, ArrayBuffers, or Uint8Arrays into HTML elements, as well as experimental parseAsync and renderDocument APIs for granular document modification. The library requires jszip to function and supports configurable options for page breaking, headers, footers, and Base64URL image encoding.

Tokens
3K
Snippets
5
Records
9
Agent score
35%

What's inside docx-preview

  1. How page breaking works in docxjs

    master

    The library supports page breaking in three scenarios:

    1. Manual page breaks: When a user inserts <w:br w:type="page"/>.
    2. Application page breaks: When an editor like MS Word inserts <w:lastRenderedPageBreak/>. Note: To respect these, you must set ignoreLastRenderedPageBreak: false in your options.
    3. Page settings changes: Such as switching from portrait to landscape.

    Real-time page breaking (calculating breaks on every insertion) is not implemented for performance reasons. For better accuracy, use editors that insert <w:lastRenderedPageBreak/> or insert manual breaks where needed.

  3. Render a DOCX document to HTML using renderAsync

    master

    The primary way to use the library is via the renderAsync method. This method takes a document (as a Blob, ArrayBuffer, or Uint8Array) and renders it into a specified HTMLElement container.

    Note: The library requires jszip to function. If using in a browser via <script> tags, you must include jszip before docx-preview.

    <!-- lib uses jszip -->
<script src="https://unpkg.com/jszip/dist/jszip.min.js"></script>
<script src="docx-preview.min.js"></script>
<script>
    var docData = <document Blob>;

    docx.renderAsync(docData, document.getElementById("container"))
        .then(x => console.log("docx: finished"));
</script>
<body
    ...
    <div id="container"></div>
    ...
</body>
    <!--lib uses jszip-->
<script src="https://unpkg.com/jszip/dist/jszip.min.js"></script>
<script src="docx-preview.min.js"></script>
<script>
    var docData = <document Blob>;

    docx.renderAsync(docData, document.getElementById("container"))
        .then(x => console.log("docx: finished"));
</script>
<body
    ...
    <div id="container"></div
    ...
</body>

  4. Configure rendering options for renderAsync

    master

    The renderAsync method accepts an options object to customize the output.

    Key options include:

    • className: Prefix for default and document style classes (default: "docx").
    • inWrapper: Whether to render a wrapper around content (default: true).
    • breakPages: Enables page breaking on page breaks (default: true).
    • ignoreLastRenderedPageBreak: If true, ignores <w:lastRenderedPageBreak/> elements (default: true). Set to false to respect application-inserted breaks.
    • renderHeaders, renderFooters, renderFootnotes, renderEndnotes: Boolean flags to enable/disable these sections (defaults vary).
    • useBase64URL: If true, converts images/fonts to base64 URL; otherwise uses URL.createObjectURL (default: false).
    • experimental: Enables experimental features like tab stops calculation (default: false).
    renderAsync(
    document: Blob | ArrayBuffer | Uint8Array, // could be any type that supported by JSZip.loadAsync
    bodyContainer: HTMLElement, //element to render document content,
    styleContainer: HTMLElement, //element to render document styles, numbeings, fonts. If null, bodyContainer will be used.
    options: {
        className: string = "docx", //class name/prefix for default and document style classes
        inWrapper: boolean = true, //enables rendering of wrapper around document content
        hideWrapperOnPrint: boolean = false, //disable wrapper styles on print
        ignoreWidth: boolean = false, //disables rendering width of page
        ignoreHeight: boolean = false, //disables rendering height of page
        ignoreFonts: boolean = false, //disables fonts rendering
        breakPages: boolean = true, //enables page breaking on page breaks
        ignoreLastRenderedPageBreak: boolean = true, //disables page breaking on lastRenderedPageBreak elements
        experimental: boolean = false, //enables experimental features (tab stops calculation)
        trimXmlDeclaration: boolean = true, //if true, xml declaration will be removed from xml documents before parsing
        useBase64URL: boolean = false, //if true, images, fonts, etc. will be converted to base 64 URL, otherwise URL.createObjectURL is used
        renderChanges: false, //enables experimental rendering of document changes (inserions/deletions)
        renderHeaders: true, //enables headers rendering
        renderFooters: true, //enables footers rendering
        renderFootnotes: true, //enables footnotes rendering
        renderEndnotes: true, //enables endnotes rendering
        renderComments: false, //enables experimental comments rendering
        renderAltChunks: true, //enables altChunks (html parts) rendering
        debug: boolean = false, //enables additional logging
        h: ({ ns, tagName, className, style, children, ...props } | Node | string): Node, //experimental hook for HTML rendering, default implementation - defaultOptions.h
    }): Promise<WordDocument>

  5. Experimental API: parseAsync and renderDocument

    master

    The following methods are considered experimental/internal and are used to modify a document before rendering. The renderAsync function is actually a combination of these two:

    • parseAsync(document, options): Parses the document and returns an internal WordDocument object.
    • renderDocument(wordDocument, options): Renders the internal WordDocument object and returns a list of Node[].

    Use these if you need to intercept and modify the document structure before it is converted to HTML.

    // this API could be used to modify document before rendering
// renderAsync = parseAsync + renderDocument

// parse document and return internal document object
parseAsync(
    document: Blob | ArrayBuffer | Uint8Array,
    options: Options
): Promise<WordDocument>

// render internal document object and return list of nodes
renderDocument(
    wordDocument: WordDocument,
    options: Options
): Promise<Node[]>

  7. Render a DOCX file using renderAsync()

    master

    The renderAsync function is the primary high-level entry point for displaying a DOCX file in a web application. It handles parsing the document data and rendering the resulting HTML nodes into specified DOM containers.

    It accepts the document data (as a Blob or other compatible type), a bodyContainer where the document content will be injected, and an optional styleContainer for CSS styles. It returns a Promise that resolves to the parsed document object.

  9. Configure docx-preview rendering options

    master

    You can pass a Partial<Options> object to renderAsync, renderDocument, or parseAsync to customize the rendering behavior.

    Key configuration options include:

    • breakPages: (boolean) Whether to insert page breaks. Defaults to true.
    • className: (string) The CSS class applied to the document wrapper. Defaults to "docx".
    • renderHeaders, renderFooters, renderFootnotes, renderEndnotes: (boolean) Controls whether these specific document elements are rendered. Defaults to true.
    • renderComments: (boolean) Whether to render comments. Defaults to false.
    • renderChanges: (boolean) Whether to render tracked changes. Defaults to false.
    • renderAltChunks: (boolean) Whether to render alternative content chunks. Defaults to true.
    • debug: (boolean) Enables debug mode. Defaults to false.
    • experimental: (boolean) Enables experimental features. Defaults to false.
    • ignoreWidth, ignoreHeight, ignoreFonts: (boolean) If true, ignores these specific attributes during rendering. Defaults to false.
    • inWrapper: (boolean) Whether to wrap the document in a container. Defaults to true.
    • hideWrapperOnPrint: (boolean) Whether to hide the wrapper when printing. Defaults to false.
    • useBase64URL: (boolean) Whether to use Base64URL encoding. Defaults to false.
    • h: (function) A custom hyperscript-like function for creating elements.
    export interface Options {
    inWrapper: boolean;
    hideWrapperOnPrint: boolean;
    ignoreWidth: boolean;
    ignoreHeight: boolean;
    ignoreFonts: boolean;
    breakPages: boolean;
    debug: boolean;
    experimental: boolean;
    className: string;
    trimXmlDeclaration: boolean;
    renderHeaders: boolean;
    renderFooters: boolean;
    renderFootnotes: boolean;
    renderEndnotes: boolean;
    ignoreLastRenderedPageBreak: boolean;
    useBase64URL: boolean;
    renderChanges: boolean;
    renderComments: boolean;
    renderAltChunks: boolean;
    h: typeof h;
}