Nodes

Section

The one node that holds other nodes, and the heading its title becomes.

The only construct that nests today. Its title carries into the document outline, so the structure you write is the structure the reader sees.

Helpers: section, Section
Node kind: section
Category: Structure
Resolves: Locally
Children: Any node, including other sections. No depth limit.

Option	Type	What it does
`id` required	`string`	Stable address for the node. Generation endpoints target it and build artifacts diff on it, so treat a rename as a breaking change.
`title` required	`string`	The heading printed above the children, and the outline entry.
`nodes`	`NodeComponent[]`	The children. Passed as the second argument, as the `nodes` option, or as JSX children of `<Section>` — the three are the same call.
`derivers`	`DeriverInvocation[]`	Values computed before the node resolves, written to `derived.*` and readable from a template token. Built with `derive()`.

Writing one

A section takes its options and its children — node components, the same values you would place at the top level of a document:

import { section } from "docxcelerate";

export const Opening = section<MemberData>({ id: "opening", title: "Your renewal" }, [
  Greeting,
  PriceChange,
]);

In TSX the same call reads as markup:

<Section id="opening" title="Your renewal">
  <Greeting />
  <PriceChange />
</Section>

Both produce the same tree. Templates covers when each form earns its keep.

Children can be anything

Paragraphs, images, graphs, a contents marker, or further sections. No other node has children, so the depth of a document is the depth of its sections.

Nothing about a node changes because it moved inside one: it resolves the same way at any depth, and its id gains no prefix.

Titles carry into the outline

title is required, and it is not decoration — it becomes the heading above the children and the entry a contents list is built from. A group that wants no heading wants no section; put the nodes in the document directly.

Variants

A titled group

src/nodes/section/basic.node.ts

Two paragraphs under one heading — the common case.

import { section } from "docxcelerate";
import { PriceChange } from "../paragraph/conditional.node.ts";
import { Greeting } from "../paragraph/static.node.ts";
import type { SampleData } from "../sample-data.ts";

/**
 * A section takes an id, a title and its children. The children are the same
 * node components you would place at the top level.
 */
export const Opening = section<SampleData>({ id: "opening", title: "Your renewal" }, [
  Greeting,
  PriceChange,
]);

section · a titled group Open ↗

What it resolves to

The node as it appears in the DocumentModel: the JSON a renderer is handed. No styling, no layout.

{
  "id": "opening",
  "kind": "section",
  "title": "Your renewal",
  "children": [
    {
      "id": "greeting",
      "kind": "paragraph",
      "mode": "static",
      "text": "Dear Adaeze Nkemelu,"
    },
    {
      "id": "price-change",
      "kind": "paragraph",
      "mode": "static",
      "text": "Your Peak Anytime membership is rising by 5.1%, from £468 to £492 a year. That is £41 a month from 1 October 2026."
    }
  ]
}

Mixed and nested children

src/nodes/section/nested.node.ts

A graph, then a nested section holding a graph and a dynamic paragraph.

import { section } from "docxcelerate";
import { ClassMix } from "../graph/pie.node.ts";
import { VisitsByMonth } from "../graph/bar.node.ts";
import { NextSteps } from "../paragraph/dynamic.node.ts";
import type { SampleData } from "../sample-data.ts";

/**
 * Children can be of any kind, including another section — the one place a
 * letter tree gains depth. The resolved document nests exactly as this reads.
 */
export const YourYear = section<SampleData>({ id: "your-year", title: "Your year here" }, [
  VisitsByMonth,
  section<SampleData>({ id: "activity-mix", title: "Where the time went" }, [
    ClassMix,
    NextSteps,
  ]),
]);

section · mixed and nested children Open ↗

What it resolves to

The node as it appears in the DocumentModel: the JSON a renderer is handed. No styling, no layout.

{
  "id": "your-year",
  "kind": "section",
  "title": "Your year here",
  "children": [
    {
      "id": "visits-by-month",
      "kind": "graph",
      "mode": "static",
      "graphType": "bar",
      "data": {
        "labels": [
          "Apr",
          "May",
          "Jun",
          "Jul",
          "Aug",
          "Sep"
        ],
        "series": [
          {
            "name": "Visits",
            "values": [
              11,
              14,
              9,
              16,
              18,
              12
            ]
          }
        ]
      },
      "caption": "Your visits to Riverside Leisure Centre, last six months"
    },
    {
      "id": "activity-mix",
      "kind": "section",
      "title": "Where the time went",
      "children": [
        {
          "id": "class-mix",
          "kind": "graph",
          "mode": "static",
          "graphType": "pie",
          "data": {
            "labels": [
              "Swim",
              "Strength",
              "Classes"
            ],
            "series": [
              {
                "name": "Share of visits",
                "values": [
                  42,
                  33,
                  25
                ]
              }
            ]
          },
          "caption": "How you used the centre, by activity"
        },
        {
          "id": "next-steps",
          "kind": "paragraph",
          "mode": "dynamic",
          "text": "Your membership renews automatically on 1 October 2026. Nothing is needed from you unless you want to change plan."
        }
      ]
    }
  ]
}

Notes

Depth is in the tree, not in the headings. Both shipped renderers print every section title at one level — <h2> in the browser, Heading 1 in the DOCX — however deeply it nests. The JSON nests correctly, so this is a renderer limitation, but a three-deep document will not look three-deep yet.
There is no dynamic section. An endpoint fills nodes in; it does not decide what the document contains.
An empty section renders as a lone heading. If the children come from a filter that can empty out, check that upstream.

Edit this page on GitHub ↗