HTML DSL API Reference

Complete HTML5 semantic elements DSL for building accessible, SEO-friendly web pages.

Package: codes.yousef.summon.components.html Since: 0.7.0

Overview

The HTML DSL provides composable functions that render actual HTML5 semantic elements rather than generic <div> elements with ARIA roles. This provides better:

Screen reader support - Native semantic meaning
Search engine optimization - Proper document structure
Document outline structure - Hierarchical headings and sections
Browser default styling - Consistent baseline appearance

Structural Elements

Renders an HTML <header> element for introductory content.

@Composable
fun Header(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Example:

Header(modifier = Modifier().padding(16.px)) {
    H1 { Text("Welcome to My Site") }
    Nav {
        A(href = "/home") { Text("Home") }
        A(href = "/about") { Text("About") }
    }
}

Nav

Renders an HTML <nav> element for navigation links.

@Composable
fun Nav(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Main

Renders an HTML <main> element for the dominant content. There should be only one visible <main> per page.

@Composable
fun Main(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Renders an HTML <footer> element for footer content (copyright, author info, related links).

@Composable
fun Footer(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Section

Renders an HTML <section> element for thematic grouping of content.

@Composable
fun Section(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Article

Renders an HTML <article> element for self-contained compositions (blog posts, news articles, comments).

@Composable
fun Article(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Aside

Renders an HTML <aside> element for tangentially related content (sidebars, pull quotes).

@Composable
fun Aside(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Address

Renders an HTML <address> element for contact information.

@Composable
fun Address(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Hgroup

Renders an HTML <hgroup> element for heading groups with subheadings.

@Composable
fun Hgroup(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Search

Renders an HTML <search> element for search form containers.

@Composable
fun Search(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Text Elements

Headings (H1-H6)

@Composable fun H1(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)
@Composable fun H2(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)
@Composable fun H3(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)
@Composable fun H4(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)
@Composable fun H5(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)
@Composable fun H6(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)

Example:

Article {
    H1 { Text("Main Title") }
    H2 { Text("Subtitle") }
    P { Text("Content paragraph...") }
}

Paragraph (P)

@Composable
fun P(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Blockquote

Extended quotation with optional citation URL.

@Composable
fun Blockquote(
    cite: String? = null,
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Example:

Blockquote(cite = "https://example.com/source") {
    P { Text("To be or not to be, that is the question.") }
}

Pre (Preformatted Text)

Preserves whitespace and line breaks.

@Composable
fun Pre(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Code

Inline computer code. For code blocks, wrap inside Pre.

@Composable
fun Code(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Example:

Pre {
    Code {
        Text("fun main() {\n    println(\"Hello, World!\")\n}")
    }
}

Text Formatting Elements

Function	Element	Purpose
`Strong`	`<strong>`	Strong importance (bold)
`Em`	`<em>`	Emphatic stress (italic)
`Small`	`<small>`	Side comments, fine print
`Mark`	`<mark>`	Highlighted text
`Del`	`<del>`	Deleted text
`Ins`	`<ins>`	Inserted text
`Sub`	`<sub>`	Subscript
`Sup`	`<sup>`	Superscript
`S`	`<s>`	Strikethrough (no longer relevant)
`U`	`<u>`	Unarticulated annotation
`B`	`<b>`	Bring attention (bold style)
`I`	`<i>`	Idiomatic text (italic style)

Del and Ins with metadata:

@Composable
fun Del(
    cite: String? = null,
    datetime: String? = null,
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

@Composable
fun Ins(
    cite: String? = null,
    datetime: String? = null,
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

List Elements

Unordered List (Ul)

@Composable
fun Ul(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Ordered List (Ol)

@Composable
fun Ol(
    start: Int? = null,
    reversed: Boolean = false,
    type: String? = null,  // "1", "a", "A", "i", "I"
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

List Item (Li)

@Composable
fun Li(
    value: Int? = null,  // For ordered lists
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Example:

Ul(modifier = Modifier().listStyleType("disc")) {
    Li { Text("First item") }
    Li { Text("Second item") }
    Li { Text("Third item") }
}

Ol(start = 5, type = "a") {
    Li { Text("Item e") }
    Li { Text("Item f") }
}

Description List (Dl, Dt, Dd)

@Composable fun Dl(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)
@Composable fun Dt(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)
@Composable fun Dd(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)

Example:

Dl {
    Dt { Text("HTML") }
    Dd { Text("HyperText Markup Language") }

    Dt { Text("CSS") }
    Dd { Text("Cascading Style Sheets") }
}

Semantic list for interactive commands.

@Composable
fun Menu(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Table Elements

Table Structure

@Composable fun Table(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)
@Composable fun Thead(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)
@Composable fun Tbody(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)
@Composable fun Tfoot(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)
@Composable fun Tr(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)

Table Cells

@Composable
fun Th(
    scope: String? = null,  // "row", "col", "rowgroup", "colgroup"
    colspan: Int? = null,
    rowspan: Int? = null,
    headers: String? = null,
    abbr: String? = null,
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

@Composable
fun Td(
    colspan: Int? = null,
    rowspan: Int? = null,
    headers: String? = null,
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Caption and Column Groups

@Composable fun Caption(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)
@Composable fun Colgroup(span: Int? = null, modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit = {})
@Composable fun Col(span: Int? = null, modifier: Modifier = Modifier())

Complete Table Example:

Table(modifier = Modifier().width("100%").borderCollapse("collapse")) {
    Caption { Text("Monthly Sales") }
    Thead {
        Tr {
            Th(scope = "col") { Text("Month") }
            Th(scope = "col") { Text("Sales") }
        }
    }
    Tbody {
        Tr {
            Td { Text("January") }
            Td { Text("$10,000") }
        }
        Tr {
            Td { Text("February") }
            Td { Text("$12,000") }
        }
    }
    Tfoot {
        Tr {
            Th(scope = "row") { Text("Total") }
            Td { Text("$22,000") }
        }
    }
}

Interactive Elements

Details/Summary

Native collapsible content without JavaScript.

@Composable
fun Details(
    open: Boolean = false,
    onToggle: ((Boolean) -> Unit)? = null,
    name: String? = null,  // For accordion behavior
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

@Composable
fun Summary(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Example:

// Uncontrolled (browser manages state)
Details {
    Summary { Text("Click to expand") }
    P { Text("Hidden content revealed when expanded") }
}

// Controlled (you manage state)
var isExpanded by remember { mutableStateOf(false) }
Details(open = isExpanded, onToggle = { isExpanded = it }) {
    Summary { Text("FAQ Item") }
    P { Text("Answer to the question...") }
}

// Accordion (only one open at a time with same name)
Details(name = "faq") {
    Summary { Text("Question 1") }
    P { Text("Answer 1") }
}
Details(name = "faq") {
    Summary { Text("Question 2") }
    P { Text("Answer 2") }
}

Dialog

Native dialog/modal element.

@Composable
fun Dialog(
    open: Boolean = false,
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Inline Elements

Links (A)

@Composable
fun A(
    href: String,
    target: String? = null,  // "_blank", "_self", "_parent", "_top"
    rel: String? = null,
    download: String? = null,
    hreflang: String? = null,
    type: String? = null,
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Span

Generic inline container.

@Composable
fun Span(
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit
)

Semantic Inline Elements

Function	Element	Purpose
`Time`	`<time>`	Date/time with machine-readable `datetime`
`Abbr`	`<abbr>`	Abbreviation with `title` expansion
`Cite`	`<cite>`	Citation/reference (titles of works)
`Q`	`<q>`	Short inline quotation
`Kbd`	`<kbd>`	Keyboard input
`Samp`	`<samp>`	Sample output
`Var`	`<var>`	Variable (math/programming)
`Dfn`	`<dfn>`	Definition term
`Data`	`<data>`	Machine-readable value
`Bdi`	`<bdi>`	Bidirectional isolation
`Bdo`	`<bdo>`	Bidirectional override

Examples:

Time(datetime = "2026-02-05") { Text("February 5, 2026") }

Abbr(title = "HyperText Markup Language") { Text("HTML") }

Q(cite = "https://example.com") { Text("Quoted text") }

Kbd { Text("Ctrl") } + Kbd { Text("C") }

Ruby Annotations (Ruby, Rt, Rp)

For East Asian character pronunciation guides.

Ruby {
    Text("漢")
    Rp { Text("(") }
    Rt { Text("かん") }
    Rp { Text(")") }
}

Line Breaks

@Composable fun Br(modifier: Modifier = Modifier())
@Composable fun Wbr(modifier: Modifier = Modifier())  // Word break opportunity

Media Elements

Figure/Figcaption

@Composable fun Figure(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)
@Composable fun Figcaption(modifier: Modifier = Modifier(), content: @Composable FlowContent.() -> Unit)

Example:

Figure {
    Image(src = "/chart.png", alt = "Sales chart")
    Figcaption { Text("Figure 1: Quarterly sales comparison") }
}

Embedded Content

@Composable
fun Iframe(
    src: String,
    title: String,  // Required for accessibility
    width: String? = null,
    height: String? = null,
    sandbox: String? = null,
    allow: String? = null,
    loading: String? = null,
    referrerpolicy: String? = null,
    modifier: Modifier = Modifier()
)

@Composable
fun Embed(
    src: String,
    type: String,
    width: String? = null,
    height: String? = null,
    modifier: Modifier = Modifier()
)

@Composable
fun ObjectTag(
    data: String? = null,
    type: String? = null,
    width: String? = null,
    height: String? = null,
    name: String? = null,
    form: String? = null,
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit = {}
)

Audio/Video Sources

@Composable
fun Source(
    src: String? = null,
    type: String? = null,
    srcset: String? = null,
    sizes: String? = null,
    media: String? = null,
    modifier: Modifier = Modifier()
)

@Composable
fun Track(
    src: String,
    kind: String = "subtitles",
    srclang: String? = null,
    label: String? = null,
    default: Boolean = false,
    modifier: Modifier = Modifier()
)

@Composable
fun Audio(
    src: String? = null,
    controls: Boolean = true,
    autoplay: Boolean = false,
    loop: Boolean = false,
    muted: Boolean = false,
    preload: String? = null,
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit = {}
)

Meter

Scalar measurement within a known range.

@Composable
fun Meter(
    value: Double,
    min: Double = 0.0,
    max: Double = 1.0,
    low: Double? = null,
    high: Double? = null,
    optimum: Double? = null,
    modifier: Modifier = Modifier(),
    content: @Composable FlowContent.() -> Unit = {}
)

Example:

Meter(value = 0.7, min = 0.0, max = 1.0, low = 0.3, high = 0.8, optimum = 1.0) {
    Text("70%")
}

Migration from SemanticHTML

The components/html/ package replaces the deprecated seo/routes/SemanticHTML.kt functions:

Old (SemanticHTML.kt)	New (components/html/)
`Header { }`	`Header { }`
`Main { }`	`Main { }`
`Nav { }`	`Nav { }`
`Article { }`	`Article { }`
`Section { }`	`Section { }`
`Aside { }`	`Aside { }`
`Footer { }`	`Footer { }`
`Heading(level = 1) { }`	`H1 { }`
`Figure { }`	`Figure { }`
`FigCaption { }`	`Figcaption { }`

HTML DSL API Reference

Overview

Structural Elements

Header

Nav

Main

Footer

Section

Article

Aside

Address

Hgroup

Search

Text Elements

Headings (H1-H6)

Paragraph (P)

Blockquote

Pre (Preformatted Text)

Code

Text Formatting Elements

List Elements

Unordered List (Ul)

Ordered List (Ol)

List Item (Li)

Description List (Dl, Dt, Dd)

Menu

Table Elements

Table Structure

Table Cells

Caption and Column Groups

Interactive Elements

Details/Summary

Dialog

Inline Elements

Links (A)

Span

Semantic Inline Elements

Ruby Annotations (Ruby, Rt, Rp)

Line Breaks

Media Elements

Figure/Figcaption

Embedded Content

Audio/Video Sources

Meter

Migration from SemanticHTML

See Also