Rendering HTML

HTML tags

Kilua provides many functions to render all standard HTML tags. Almost all of them have names directly corresponding to tag names. The exceptions are these HTML tags:

• <input>, which can be rendered using many different functions, dedicated for different types of inputs (e.g. text, checkbox, radiobutton, upload, color etc.)

• <a>, rendered with a link() function (in my opinion a() is not very convenient name for one of the most important functions)

• <link>, rendered with a linkTag() function (to avoid clash with the above)

• <map>, rendered with a mapTag() function (to avoid clash with Kotlin maps)

• <object>, rendered with an objectTag() function (to avoid clash with Kotlin object keyword)

• <var>, rendered with a varTag() function (to avoid clash with Kotlin var keyword)

There is a dedicated kilua-svg module to render <svg> tags containing vector graphics.

You can also render custom HTML tags, by using tag() function.

tag("my-custom-tag") {
    id("my-id")
}

HTML attributes

Most HTML attributes are optional, but for some HTML tags they are almost always used (e.g. <img src="..."> or <a href="...">). In Kilua such attributes are usually available directly as composable functions parameters.

div {
    link("https://kotlinlang.org/", target = "_blank") {
        img("img/kotlin.png", alt = "Kotlin")
    }
}

Some attributes can only by used with functions inside the component body.

link("/logout", icon = "bi bi-box-arrow-right") {
    title("Logout")
    ariaLabel("Logout")
}

Other standard or custom attributes can be declared using an attribute() function.

button(className = "navbar-toggler") {
    ariaLabel("Show navigation")
    attribute("data-bs-toggle", "collapse")
    attribute("data-bs-target", "#navbarNav")
    attribute("aria-controls", "navbarNav")
    attribute("aria-expanded", "false")
    span("navbar-toggler-icon")
}

Text content

You can declare textual content of HTML tags with a textNode() function, which also has a convenient extension operator +. It can be used like this:

div {
    p {
        +"Paragraph content"
    }
}

For some often used cases Kilua defines dedicated functions (by adding t to the name), which take the text content as the first parameter - these are: bt(), divt(), emt(), h1t(), h2t(), h3t(), h4t(), h5t(), h6t(), it(), lit(), pt(), pret(), st(), smallt(), spant(), strongt(), subt(), supt(), ut().

div {
    pt("Paragraph content")
}

Raw HTML code

The text content rendered with textNode() function (or + operator) is always rendered as plain text (any HTML code is escaped). But you can also render raw HTML code with the help of rawHtml() and rawHtmlBlock() functions. The first one renders rich content inside an additional <span style="display: contents;"></span> tag and the second one inside a <div style="display: contents;"></div> tag. You can choose whether you need an inline or a block element based on your HTML structure.

div {
    rawHtml("Some rich text <b>with bold</b> and <i>italic</i>.")
}

When using raw HTML make sure your code is safe from any XSS vulnerabilities. If you need to display some external data, always sanitize it before rendering with some reliable library. You can use kilua-sanitize-html module, which is based on proven sanitize-html project.