HTML builder example pattern in Kotlin - Deep Dive

Overview - HTML builder example pattern

What is it?

The HTML builder example pattern in Kotlin is a way to create HTML documents programmatically using Kotlin functions and classes. It lets you write HTML structure inside Kotlin code with a clear, readable, nested style using lambdas with receivers, instead of writing raw strings or concatenations. The result is code that mirrors the real HTML tree while being fully type-safe and maintainable.

Why it matters

Without this pattern, generating HTML in code means writing long string concatenations which are hard to read, error-prone, and nearly impossible to validate. The HTML builder pattern solves this by making HTML creation structured and safe, especially when the HTML depends on dynamic data. It reduces bugs, improves readability, and speeds up writing complex HTML structures in production applications.

Where it fits

Before learning this, you should know basic Kotlin syntax, functions, classes, and lambdas. After this, you can explore Kotlin DSLs (Domain Specific Languages) broadly, the Ktor web framework's HTML DSL, and advanced Kotlin features like lambdas with receivers and DSL markers. This pattern is a key stepping stone to writing expressive, structured Kotlin code.

Mental Model

Core Idea

The HTML builder pattern lets you write HTML as nested Kotlin function calls that mirror the HTML tag structure, making code readable, type-safe, and easy to manipulate before rendering.

Think of it like...

Think of it like building a house with LEGO blocks — each block is a function representing an HTML tag, and you snap them together in the right order to form the full structure. You build the whole house in memory first, then take a photo of it (render to string) when you are done.

html()
├── head()
│   └── title()
└── body()
    ├── h1()
    └── p()

Build-Up - 8 Steps

1

Foundation

Basic Kotlin functions for HTML tags

Concept: Represent HTML tags as Kotlin functions that take lambdas, enabling nested structure.

fun html(content: () -> Unit) { println("") content() println("") } fun body(content: () -> Unit) { println("") content() println("") } fun h1(text: String) { println("

$text

") } fun p(text: String) { println("

$text

") } fun main() { html { body { h1("Welcome") p("This is a paragraph.") } } }

Result

Welcome

This is a paragraph.

Understanding that functions can take other functions as parameters lets us mimic HTML's nested structure directly in Kotlin code without any strings.

2

Foundation

Building a Tag class with children

Concept: Represent tags as objects that hold children, enabling tree building before rendering.

open class Tag(val name: String) { val children = mutableListOf() var text: String? = null fun render(): String { val content = children.joinToString("") { it.render() } + (text ?: "") return "<$name>$content" } fun tag(name: String, init: Tag.() -> Unit) { val t = Tag(name) t.init() children.add(t) } } fun html(init: Tag.() -> Unit): Tag { val root = Tag("html") root.init() return root } fun main() { val page = html { tag("body") { tag("h1") { text = "Title" } tag("p") { text = "Paragraph." } } } println(page.render()) }

Result

Title

Paragraph.

Representing tags as objects with a children list models the HTML tree in memory, allowing flexible manipulation or reuse before producing the final HTML string.

3

Intermediate

Using lambdas with receivers for natural syntax

🤔Before reading on: do you think lambdas with receivers change what 'this' refers to inside the lambda? Commit to your answer.

Concept: Apply lambdas with receivers so nested tag functions are called directly on the parent tag, mimicking HTML syntax.

class HTML { val children = mutableListOf() fun body(init: BODY.() -> Unit) { val b = BODY() b.init() children.add(b) } fun render(): String = "" + children.joinToString("") { it.render() } + "" } open class Tag(val name: String) { val children = mutableListOf() var text: String? = null fun render(): String { val content = children.joinToString("") { it.render() } + (text ?: "") return "<$name>$content" } } class BODY : Tag("body") { fun h1(init: Tag.() -> Unit) { val t = Tag("h1"); t.init(); children.add(t) } fun p(init: Tag.() -> Unit) { val t = Tag("p"); t.init(); children.add(t) } } fun html(init: HTML.() -> Unit): HTML { val h = HTML(); h.init(); return h } fun main() { val page = html { body { h1 { text = "Hello" } p { text = "Paragraph text." } } } println(page.render()) }

Result

Hello

Paragraph text.

Lambdas with receivers change what 'this' refers to inside the block, letting you call child tag functions naturally without repeating object names — the key to readable DSL syntax.

4

Intermediate

Adding attributes to tags

🤔Before reading on: do you think attributes should be stored as raw strings or as a structured key-value map? Commit to your answer.

Concept: Extend Tag to store HTML attributes as a key-value map and include them when rendering.

open class Tag(val name: String) { val children = mutableListOf() var text: String? = null val attributes = mutableMapOf() fun setAttribute(key: String, value: String) { attributes[key] = value } fun render(): String { val attrs = attributes.entries.joinToString(" ") { "${it.key}=\"${it.value}\"" } val openTag = if (attrs.isNotEmpty()) "<$name $attrs>" else "<$name>" val content = children.joinToString("") { it.render() } + (text ?: "") return "$openTag$content" } } fun html(init: Tag.() -> Unit): Tag { val root = Tag("html") root.init() return root } fun main() { val page = html { tag("body") { tag("h1") { setAttribute("style", "color:blue") text = "Styled Header" } tag("p") { setAttribute("id", "intro") setAttribute("class", "text") text = "Paragraph with attributes." } } } println(page.render()) }

Result

Styled Header

Paragraph with attributes.

Storing attributes as a map is safer than string concatenation — it prevents malformed HTML, avoids duplicates, and makes dynamic attribute setting easy to manage.

5

Intermediate

Creating specific tag classes for type safety

🤔Before reading on: do you think using a generic Tag class or specific classes per tag is better for catching wrong nesting at compile time? Commit to your answer.

Concept: Define dedicated classes for each HTML tag so only valid child tags can be added, catching nesting errors at compile time.

open class Tag(val name: String) { val children = mutableListOf() var text: String? = null val attributes = mutableMapOf() fun initTag(tag: T, init: T.() -> Unit): T { tag.init() children.add(tag) return tag } fun render(): String { val attrs = attributes.entries.joinToString(" ") { "${it.key}=\"${it.value}\"" } val openTag = if (attrs.isNotEmpty()) "<$name $attrs>" else "<$name>" val content = children.joinToString("") { it.render() } + (text ?: "") return "$openTag$content" } } class HTML : Tag("html") { fun body(init: BODY.() -> Unit) = initTag(BODY(), init) } class BODY : Tag("body") { fun h1(init: H1.() -> Unit) = initTag(H1(), init) fun p(init: P.() -> Unit) = initTag(P(), init) } class H1 : Tag("h1") class P : Tag("p") fun html(init: HTML.() -> Unit): HTML { val h = HTML(); h.init(); return h } fun main() { val page = html { body { h1 { text = "Type-safe Header" } p { text = "Type-safe paragraph." } } } println(page.render()) }

Result

Type-safe Header

Type-safe paragraph.

Dedicated tag classes make invalid nesting (like putting a body inside a p) a compile error, not a runtime bug — this is the core advantage of type-safe builders over string templates.

6

Advanced

Using @DslMarker to prevent scope leaks

🤔Before reading on: do you think Kotlin allows calling an outer builder's function from inside a deeply nested lambda? Commit to yes or no.

Concept: Apply @DslMarker to prevent accidentally calling outer scope functions from inside nested builder lambdas.

@DslMarker annotation class HtmlTagMarker @HtmlTagMarker open class Tag(val name: String) { val children = mutableListOf() var text: String? = null val attributes = mutableMapOf() fun initTag(tag: T, init: T.() -> Unit): T { tag.init() children.add(tag) return tag } fun render(): String { val attrs = attributes.entries.joinToString(" ") { "${it.key}=\"${it.value}\"" } val openTag = if (attrs.isNotEmpty()) "<$name $attrs>" else "<$name>" val content = children.joinToString("") { it.render() } + (text ?: "") return "$openTag$content" } } @HtmlTagMarker class HTML : Tag("html") { fun body(init: BODY.() -> Unit) = initTag(BODY(), init) } @HtmlTagMarker class BODY : Tag("body") { fun h1(init: H1.() -> Unit) = initTag(H1(), init) fun p(init: P.() -> Unit) = initTag(P(), init) } @HtmlTagMarker class H1 : Tag("h1") @HtmlTagMarker class P : Tag("p") fun html(init: HTML.() -> Unit): HTML { val h = HTML(); h.init(); return h } fun main() { val page = html { body { h1 { text = "DSL Marker Demo" } // body { } here would now cause a compile error — scope leak prevented p { text = "Clean scope." } } } println(page.render()) }

Result

DSL Marker Demo

Clean scope.

Without @DslMarker, Kotlin allows calling the outer html-level body() function from inside a nested p lambda — a subtle bug. The annotation makes the compiler flag this as an error, enforcing correct scope.

7

Advanced

Creating reusable components with extension functions

🤔Before reading on: can you think of how extension functions on Tag could let you define reusable HTML components? Commit to your answer.

Concept: Use extension functions on builder classes to extract reusable HTML fragments, reducing repetition.

@DslMarker annotation class HtmlTagMarker @HtmlTagMarker open class Tag(val name: String) { val children = mutableListOf() var text: String? = null fun initTag(tag: T, init: T.() -> Unit): T { tag.init(); children.add(tag); return tag } fun render(): String { val content = children.joinToString("") { it.render() } + (text ?: "") return "<$name>$content" } } @HtmlTagMarker class HTML : Tag("html") { fun body(init: BODY.() -> Unit) = initTag(BODY(), init) } @HtmlTagMarker class BODY : Tag("body") { fun h1(init: H1.() -> Unit) = initTag(H1(), init) fun p(init: P.() -> Unit) = initTag(P(), init) fun div(init: Tag.() -> Unit) = initTag(Tag("div"), init) } @HtmlTagMarker class H1 : Tag("h1") @HtmlTagMarker class P : Tag("p") fun html(init: HTML.() -> Unit): HTML { val h = HTML(); h.init(); return h } // Reusable component as extension function fun BODY.pageHeader(title: String, subtitle: String) { div { initTag(H1()) { text = title } initTag(P()) { text = subtitle } } } fun main() { val page = html { body { pageHeader("My Site", "Welcome to the homepage.") p { text = "Main content here." } } } println(page.render()) }

Result

My Site

Welcome to the homepage.

Main content here.

Extension functions on builder classes let you define reusable HTML components that fit seamlessly into the DSL syntax — the same way you would extract a function in regular code to avoid repetition.

8

Expert

Optimizing rendering with StringBuilder

🤔Before reading on: do you think string concatenation with + inside render() is efficient for deeply nested HTML trees? Commit to yes or no.

Concept: Replace string concatenation in render() with a shared StringBuilder to reduce object allocation for large HTML trees.

@DslMarker annotation class HtmlTagMarker @HtmlTagMarker open class Tag(val name: String) { val children = mutableListOf() var text: String? = null val attributes = mutableMapOf() fun initTag(tag: T, init: T.() -> Unit): T { tag.init(); children.add(tag); return tag } fun render(sb: StringBuilder) { sb.append("<$name") attributes.forEach { (k, v) -> sb.append(" $k=\"$v\"") } sb.append(">") text?.let { sb.append(it) } children.forEach { it.render(sb) } sb.append("") } fun render(): String = StringBuilder().also { render(it) }.toString() } @HtmlTagMarker class HTML : Tag("html") { fun body(init: BODY.() -> Unit) = initTag(BODY(), init) } @HtmlTagMarker class BODY : Tag("body") { fun h1(init: H1.() -> Unit) = initTag(H1(), init) fun p(init: P.() -> Unit) = initTag(P(), init) } @HtmlTagMarker class H1 : Tag("h1") @HtmlTagMarker class P : Tag("p") fun html(init: HTML.() -> Unit): HTML { val h = HTML(); h.init(); return h } fun main() { val page = html { body { h1 { attributes["id"] = "main-title" text = "Optimized Builder" } p { text = "Rendered efficiently with StringBuilder." } } } println(page.render()) }

Result

Optimized Builder

Rendered efficiently with StringBuilder.

Each + on a String creates a new object. For a tree with hundreds of nodes, passing a single StringBuilder through the recursive render() call eliminates this overhead completely — a real production concern for server-side HTML generation.

Under the Hood

The HTML builder pattern represents HTML tags as Kotlin objects forming a tree in memory. Each Tag object stores its name, a list of child Tag objects, optional text content, and an attributes map. When the builder lambda runs, it populates this tree using lambdas with receivers — so each nested call executes in the context of its parent tag object. Rendering traverses this tree recursively, appending tag open/close strings and content into a StringBuilder. Kotlin's @DslMarker annotation prevents the compiler from resolving functions from outer receiver scopes inside nested lambdas, enforcing correct nesting at compile time.

Why designed this way?

This pattern was designed because string concatenation for HTML is fragile — misspelled tags, missing closing tags, and unescaped characters cause bugs that are hard to find. Kotlin's lambdas with receivers uniquely enable a syntax that looks like a config block but is actually type-safe function calls on objects. The tree-first approach separates construction from rendering, enabling manipulation, testing, or transformation of the document before output. @DslMarker was added to Kotlin specifically because early DSLs without it had subtle scope-leak bugs that were difficult to diagnose.

Builder execution flow:

html { ... }
    │
    ▼
 HTML object created
    │ body { ... } called as lambda with receiver on HTML
    ▼
 BODY object created, added to HTML.children
    │ h1 { ... } called as lambda with receiver on BODY
    ▼
 H1 object created, added to BODY.children
    │ text = "..." sets H1.text

Tree in memory:
HTML
└── BODY
    ├── H1 (text: "...")
    └── P  (text: "...")

Rendering (recursive):
HTML.render(sb)
  → sb.append("<html>")
  → BODY.render(sb)
      → sb.append("<body>")
      → H1.render(sb) → "<h1>...</h1>"
      → P.render(sb)  → "<p>...</p>"
      → sb.append("</body>")
  → sb.append("</html>")

Myth Busters - 4 Common Misconceptions

Quick: Does the HTML builder generate HTML immediately when you call html { body { } }? Commit to yes or no.

Common Belief: The builder prints or produces HTML immediately as each tag function is called.

Reality: It builds a tree of Tag objects in memory first. HTML is only produced when render() is explicitly called on the root.

Why it matters: Thinking rendering is immediate leads to confusion about when the output is available and prevents you from manipulating or reusing the tree before rendering.

Quick: Without @DslMarker, can you accidentally call body() from inside a p { } block? Commit to yes or no.

Common Belief: Kotlin automatically prevents calling outer scope builder functions from inside nested lambdas.

Reality: Without @DslMarker, Kotlin resolves outer receiver functions in nested lambdas, allowing silent scope leaks that produce wrong HTML with no compiler warning.

Why it matters: Missing this causes subtle structural bugs in generated HTML that are hard to trace since the code compiles and runs without errors.

Quick: Is using a generic Tag class for all elements the same as using specific classes like H1 and P? Commit to yes or no.

Common Belief: A generic Tag class works just as well as specific subclasses for each element.

Reality: Specific classes enforce which child tags are valid at compile time. A generic Tag allows any nesting including invalid HTML like a body inside a p.

Why it matters: Generic tags shift HTML structure errors from compile time to runtime or produce silently malformed HTML, defeating the main benefit of the pattern.

Quick: Is the HTML builder pattern only for generating static pages? Commit to yes or no.

Common Belief: The builder is only useful for generating fixed HTML content known at compile time.

Reality: The pattern is primarily used for dynamic HTML — conditionals, loops, and runtime data all work naturally inside the lambdas.

Why it matters: Underestimating this limits its adoption. Dynamic HTML generation with data from databases or APIs is the most common production use case.

Expert Zone

1

@DslMarker not only prevents scope leaks at runtime but also improves IDE auto-complete — the IDE only suggests functions from the current receiver scope, not all outer scopes at once.

2

The inline modifier on tag builder functions eliminates the lambda object allocation entirely, which matters in hot paths generating many small HTML fragments per request.

3

Combining the builder pattern with Kotlin's sealed classes for tag types enables exhaustive when-expressions over the HTML tree — useful for transformations like sanitization or minification.

When NOT to use

Avoid this pattern for purely static HTML that never changes — a plain .html file is simpler, faster, and easier to hand to a designer. Also avoid it for templating where non-developers need to edit content, since they cannot work in Kotlin code. For very large documents with thousands of nodes, consider streaming output directly rather than building the full tree in memory.

Production Patterns

In production, the Ktor web framework uses this exact pattern as its HTML DSL for server-side rendering. Teams extend the base tag classes with their own reusable component functions for navigation bars, footers, and form elements. StringBuilder-based rendering is used to keep response generation fast under load. The pattern is also used in test suites to programmatically build expected HTML structures for assertion rather than comparing raw strings.

Connections

Domain-Specific Languages (DSLs)

The HTML builder is a concrete example of an internal DSL built using Kotlin language features.

Understanding this pattern reveals how Kotlin's lambdas with receivers and extension functions are the key tools for building any DSL — not just HTML builders.

Composite Design Pattern

The Tag tree is a direct application of the Composite pattern — both leaves (P, H1) and composites (BODY, HTML) implement the same render interface.

Recognising the Composite pattern here helps you apply the same tree-building technique to other structured outputs like XML, JSON, or UI component trees.

Builder Design Pattern

The DSL-style API is a fluent variant of the Builder pattern — construction and configuration happen in a single nested block rather than a chain of method calls.

Comparing this to traditional Builder pattern shows how lambdas with receivers produce more readable construction code, especially for deeply nested structures.

Common Pitfalls

#1 Forgetting to call render() and printing the Tag object directly.

Wrong approach:

val page = html { body { h1 { text = "Hi" } } }
println(page) // prints object reference, not HTML

Correct approach:

val page = html { body { h1 { text = "Hi" } } }
println(page.render()) // prints Hi

Root cause:

Misunderstanding that the builder builds a tree object, not a string. render() must be called explicitly to produce HTML output.

#2 Calling an outer scope builder function from inside a nested block when @DslMarker is not applied.

Wrong approach:

// Without @DslMarker
html {
body {
p {
body { // accidentally calling outer body() — inserts body inside p
h1 { text = "Wrong" }
}
}
}
}

Correct approach:

// With @DslMarker applied to all Tag subclasses
// The compiler rejects the inner body() call with an error:
// 'body' can't be called in this context by implicit receiver

Root cause:

Without @DslMarker, Kotlin resolves functions from all enclosing receiver scopes, allowing silent structural mistakes that produce invalid HTML.

#3 Using string concatenation in render() for large HTML trees.

Wrong approach:

fun render(): String =
"<$name>" + children.joinToString("") { it.render() } + ""

Correct approach:

fun render(sb: StringBuilder) {
sb.append("<$name>")
children.forEach { it.render(sb) }
sb.append("")
}

Root cause:

String + creates a new String object at every node. A shared StringBuilder passed through the recursive call eliminates this allocation, which becomes significant for trees with hundreds of nodes.

Key Takeaways

The HTML builder pattern represents HTML tags as Kotlin objects forming a tree in memory, rendering to a string only when explicitly requested.

Lambdas with receivers are the core Kotlin feature enabling the nested, readable DSL syntax that mirrors real HTML structure.

Specific tag subclasses (HTML, BODY, H1, P) enforce valid nesting at compile time, turning structural HTML errors into compiler errors.

@DslMarker prevents scope leaks where outer builder functions could be accidentally called inside nested lambdas, causing silent HTML structure bugs.

StringBuilder-based rendering eliminates repeated String object allocation, making the pattern efficient for server-side HTML generation under load.