Title: 'HTML' Element Construction
Version: 1.1.0
Description: Provides a deterministic, framework-agnostic Domain-Specific Language for building 'HTML' nodes and rendering them to a string.
License: MIT + file LICENSE
URL: https://github.com/sigflux/hypertext
BugReports: https://github.com/sigflux/hypertext/issues
Encoding: UTF-8
RoxygenNote: 7.3.3
Suggests: testthat (≥ 3.0.0)
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-03-07 13:49:31 UTC; mwavu
Author: Kennedy Mwavu ORCID iD [aut, cre], Sigflux [cph, fnd]
Maintainer: Kennedy Mwavu <mwavukennedy@gmail.com>
Repository: CRAN
Date/Publication: 2026-03-07 14:00:17 UTC

Escape special HTML characters

Description

Replaces &, <, >, ⁠"⁠, and ⁠'⁠ with their HTML entity equivalents.

Usage

.escape_html(x)

Arguments

x

A character string.

Value

A character string with HTML special characters escaped.

Flatten children

Description

Recursively unpack plain lists (but not hypertext.tag or hypertext.tag.list nodes) so users can pass list(tags$li("a"), tags$li("b")) as a single child argument.

Usage

.flatten_children(x)

Arguments

x

A list of children.

Value

A flat list of children.

Create a tag function for a normal (non-void) element

Description

Create a tag function for a normal (non-void) element

Usage

.make_tag(tag_name)

Create a tag function for a void (self-closing) element

Description

Create a tag function for a void (self-closing) element

Usage

.make_void_tag(tag_name)

Render a named list of attributes to a single HTML attribute string

Description

Usage

.render_attrs(attrs)

Arguments

attrs

A named list of attribute values.

Value

A single character string (leading space included when non-empty).

Render the ⁠<!DOCTYPE html>⁠ declaration

Description

Convenience wrapper around raw_html() that returns the HTML5 document-type declaration. Useful when building a full page.

Usage

doctype()

Value

A "hypertext.raw" object containing ⁠<!DOCTYPE html>⁠.

Examples

page <- tag_list(
  doctype(),
  tags$html(
    tags$head(tags$title("Home")),
    tags$body(tags$h1("Welcome"))
  )
)
render(page)

Mark a string as raw HTML

Description

Wraps one or more character strings so that render() outputs them verbatim, without escaping HTML special characters.

Usage

raw_html(...)

Arguments

...

Character strings of raw HTML /// Optional.

Details

This is useful for injecting pre-rendered HTML, inline ⁠<script>⁠/⁠<style>⁠ blocks, SVG markup, or any content that should not be entity-escaped.

Value

A character vector of class "hypertext.raw".

Examples

raw_html("<script>alert('hi')</script>")
render(tags$div(raw_html("<em>already formatted</em>")))

Render an HTML node tree to a character string

Description

Converts a hypertext.tag object (and all its descendants) into an HTML string. Text children are escaped; nested hypertext.tag children are rendered recursively.

Usage

render(x, ...)

## S3 method for class 'hypertext.tag'
render(x, file = "", write_mode = c("overwrite", "append"), ...)

## Default S3 method:
render(x, file = "", write_mode = c("overwrite", "append"), ...)

## S3 method for class 'hypertext.raw'
render(x, file = "", write_mode = c("overwrite", "append"), ...)

## S3 method for class 'list'
render(x, file = "", write_mode = c("overwrite", "append"), ...)

Arguments

x

hypertext.tag object, a string, or a list of these /// Required.

...

Further arguments passed from or to other methods.

file

String /// Optional. Path to file to print to.

write_mode

String /// Optional. Either "overwrite" (default) which overwrites the contents of file, or "append" which appends the HTML string to file.

Details

When file is provided, the rendered HTML is written to the specified file via cat() and the HTML string is returned invisibly.

Value

A single character string of HTML.

Examples

page <- tags$html(
  tags$head(
    tags$title("Home")
  ),
  tags$body(
    tags$h1("Welcome")
  )
)

# return HTML as a string:
render(page)

## Not run: 
  # write to a file:
  render(page, file = "index.html")

## End(Not run)

Create an HTML element node

Description

Low-level constructor. Named arguments become attributes; unnamed arguments become children (text or nested nodes).

Usage

tag(tag_name, ..., tag_type = c("normal", "void"))

Arguments

tag_name

String /// Required. The HTML element name.

...

Attributes (named) and children (unnamed) /// Optional.

tag_type

String /// Optional. Either "normal" (default) for a standard element with children, or "void" for a self-closing element whose children are ignored.

Value

List of class "hypertext.tag" with components tag, attrs, children, and tag_type.

Examples

# web component
tag(tag_name = "calcite-action-bar", layout = "horizontal")

# custom element with children
tag(
  tag_name = "my-card",
  class = "shadow",
  tag(tag_name = "my-card-header", "Title"),
  tag(tag_name = "my-card-body", "Content")
)

# custom void element
tag(tag_name = "my-icon", name = "home", tag_type = "void")

Create a tag list (sibling container)

Description

Useful when you want to collect sibling nodes into a single object without wrapping them in a parent element.

Usage

tag_list(...)

Arguments

...

Tags, text, or other renderable objects /// Optional.

Value

A list of class "hypertext.tag.list".

Examples

tl <- tag_list(tags$p("one"), tags$p("two"))
render(tl)

HTML tag functions

Description

A named list of functions, one per HTML5 element. Access individual tags with tags$div(...), tags$p(...), etc.

Usage

tags

Format

An object of class list of length 115.

Details

Named arguments become HTML attributes; unnamed arguments become child nodes or text content.

Boolean / valueless attributes

Pass NA or TRUE as the attribute value to produce a valueless attribute (e.g. disabled). FALSE or NULL suppresses the attribute entirely.

Multi-value attributes

Character vectors of length > 1 are collapsed with a space, so class = c("a", "b") renders as class="a b".

Examples

tags$p(class = "lead", "Hello, world!")
render(tags$div(id = "app", tags$h1("Title")))