Rendering - React Docx

import { render } from "@cordel/react-docx";

await render(<MyDocument />, "./output.docx");

Returns a Promise<string> with the output path. To keep the document in memory, for example to send it in an HTTP response or upload it, use renderToBuffer. It resolves to the file’s bytes as a Uint8Array:

import { renderToBuffer } from "@cordel/react-docx";

export async function GET() {
  const bytes = await renderToBuffer(<Invoice />);
  return new Response(bytes, {
    headers: {
      "Content-Type":
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "Content-Disposition": 'attachment; filename="invoice.docx"',
    },
  });
}

Both functions accept the same options:

Option	Description
`variables`	Values for `<Variable>` and `useVariables()`
`loadFile`	Fetches `src` strings of images, the base document and fonts, e.g. from object storage. See Image

For documents rendered from data that comes from outside the program, see Templates and testing.

Basic usage

import { render, Document, Section, H1, Paragraph } from "@cordel/react-docx";

const MyDocument = () => (
  <Document>
    <Section>
      <H1>Hello</H1>
      <Paragraph>World</Paragraph>
    </Section>
  </Document>
);

await render(<MyDocument />, "./hello.docx");

Variables

Pass dynamic data to your document:

await render(<Invoice />, "./invoice.docx", {
  variables: {
    invoiceNumber: "INV-001",
    customer: "Acme Corp",
    total: 420.00,
  },
});

Variable component

import { Variable } from "@cordel/react-docx";

const Invoice = () => (
  <Document>
    <Section>
      <H1>
        Invoice #<Variable name="invoiceNumber" />
      </H1>
      <Paragraph>
        Customer: <Variable name="customer" defaultValue="N/A" />
      </Paragraph>
    </Section>
  </Document>
);

A Variable that is not in variables and has no defaultValue rejects the render, so a missing value cannot produce an incomplete document. Pass null to render it empty on purpose.

useVariables hook

For more control:

import { useVariables } from "@cordel/react-docx";

const Invoice = () => {
  const vars = useVariables<{
    invoiceNumber: string;
    customer: string;
    total: number;
  }>();

  return (
    <Document>
      <Section>
        <H1>Invoice #{vars.invoiceNumber}</H1>
        <Paragraph>Customer: {vars.customer}</Paragraph>
        <Paragraph>
          <Text className="font-bold">Total: ${vars.total.toFixed(2)}</Text>
        </Paragraph>
      </Section>
    </Document>
  );
};

Formatting

<Variable
  name="price"
  format={(value) => `$${Number(value).toFixed(2)}`}
/>

Async data

Components can read promises with React’s use() or load with React.lazy. Rendering waits until every suspended component has its data, so the document never contains a Suspense fallback.

import { use } from "react";

const customer = fetchCustomer(id);

function BillTo() {
  const { name } = use(customer);
  return <Paragraph>Bill to: {name}</Paragraph>;
}

Create the promise outside the component (or cache it) so each render reads the same promise. A rejected promise rejects render().

Error handling

try {
  await render(<MyDocument />, "./output.docx");
  console.log("Done");
} catch (error) {
  console.error("Failed:", error);
}

render() and renderToBuffer() reject, without writing a file, when:

a component throws and no error boundary catches it;
a <Variable> was not provided and has no defaultValue;
an image cannot be loaded or is not PNG, JPEG, GIF or BMP;
an element is placed where Word cannot represent it, such as a <Section> outside <Document> or a <Paragraph> inside a <Link>.

Full example

import {
  render,
  Document,
  Section,
  H1,
  Paragraph,
  Text,
  Table,
  Thead,
  Tbody,
  Tr,
  Th,
  Td,
  useVariables,
} from "@cordel/react-docx";

interface InvoiceData {
  number: string;
  date: string;
  customer: { name: string; email: string };
  items: { name: string; qty: number; price: number }[];
}

const Invoice = () => {
  const vars = useVariables<InvoiceData>();
  const total = vars.items.reduce((sum, item) => sum + item.qty * item.price, 0);

  return (
    <Document>
      <Section>
        <H1 className="text-blue-700">Invoice #{vars.number}</H1>

        <Paragraph className="mt-4">
          <Text className="font-bold">Date: </Text>{vars.date}
        </Paragraph>
        <Paragraph>
          <Text className="font-bold">Customer: </Text>{vars.customer.name}
        </Paragraph>

        <Table className="mt-6 border">
          <Thead>
            <Tr>
              <Th className="border p-2 bg-gray-100">Item</Th>
              <Th className="border p-2 bg-gray-100">Qty</Th>
              <Th className="border p-2 bg-gray-100">Price</Th>
            </Tr>
          </Thead>
          <Tbody>
            {vars.items.map((item, i) => (
              <Tr key={i}>
                <Td className="border p-2">{item.name}</Td>
                <Td className="border p-2">{item.qty}</Td>
                <Td className="border p-2">${item.price}</Td>
              </Tr>
            ))}
          </Tbody>
        </Table>

        <Paragraph className="mt-4 text-right">
          <Text className="text-xl font-bold">Total: ${total}</Text>
        </Paragraph>
      </Section>
    </Document>
  );
};

await render(<Invoice />, "./invoice.docx", {
  variables: {
    number: "INV-001",
    date: "2024-01-15",
    customer: { name: "Acme Corp", email: "billing@acme.com" },
    items: [
      { name: "Widget", qty: 10, price: 25 },
      { name: "Gadget", qty: 5, price: 50 },
    ],
  },
});

​Basic usage

​Variables

​Variable component

​useVariables hook

​Formatting

​Async data

​Error handling

​Full example