ScalaTags

The scalatags.Text module is designed for generating HTML as Strings. It provides a set of bundles (like all, short, tags, attrs, etc.) that allow you to construct HTML structures using a type-safe DSL. The resulting fragments can be rendered to a String using .render or written directly to a java.io.Writer or java.io.OutputStream.

import scalatags.Text._

// Example of generating an HTML string
val html: String = div(
  class := "container",
  h1("Hello World"),
  p("This is Scalatags text module.")
).render

By default, all text and attribute values are HTML-escaped to prevent XSS. If you need to insert unsanitized/raw HTML, wrap the string in the raw() function.

import scalatags.Text.all._

val unsafe = "<script>alert('xss')</script>"

// Escaped: &lt;script&gt;...
val safe = p(unsafe)

// Unescaped: <script>...</n// WARNING: Use only with trusted input!
val dangerous = p(raw(unsafe))

Scalatags uses a combination of typeclasses and implicit conversions to allow for extensible rendering:

• Typeclasses: AttrValue[Builder, T] and StyleValue[Builder, T] allow you to define how specific types T are applied as attributes or styles. For example, the JsDom backend provides an implicit to bind anything convertible to js.Any into attributes.
• Implicit Conversions: These allow arbitrary types to be used as children within a Frag or TypedTag by converting them into a Modifier or Frag.

You can implement your own typeclass instances to handle complex types like Future (to add a child upon completion) or reactive variables (to update the UI when the value changes).

For Scala.js projects, you can use the JsDom backend to render directly to dom.Element objects instead of strings. This allows for direct DOM manipulation and binding of JavaScript functions to events.

// Replace scalatags.Text with scalatags.JsDom
import scalatags.JsDom._

// Renders to a DOM element
val element = div(
  onclick := { println("Clicked!") },
  "Click me!"
).render

// You can now use standard DOM APIs
val parent = element.parentElement

If you need to define CSS rules using cascading selectors (like .my-class or div.my-class), inherit from CascadingStyleSheet instead of StyleSheet.

CascadingStyleSheet provides an implicit conversion that allows you to use Cls objects directly as selectors, enabling you to write rules like myClass.selector or target specific tags with classes.

import scalatags.stylesheet._

abstract class MyCascadingStyles extends CascadingStyleSheet {
  // CascadingStyleSheet allows using class selectors directly
  // in a way that standard StyleSheet does not.
  initStyleSheet()
}

Since ScalaTags is pure Scala, you can use standard Scala control flow (if, for) and variables directly within your templates.

import scalatags.Text.all._

val items = Seq("Apple", "Banana", "Cherry")
val userLoggedIn = true

val list = div(
  if (userLoggedIn) {
    ul(
      items.map(item => li(item)).foreach(li => li)
    )
  } else {
    p("Please log in")
  }
)

Scalatags provides different backends depending on your target runtime:

• Text Backend (scalatags.Text): Used for generating HTML/XML as a String. It uses a custom text.Builder for high performance. The common alias for a tag here is type Tag = TypedTag[String].
• DOM Backend (scalatags.JsDom): Used for manipulating the browser DOM (via Scala.js). It uses dom.Element as the builder and produces various DOM element types as output. Common aliases include:
  • type HtmlTag = TypedTag[dom.HTMLElement]
  • type SvgTag = TypedTag[dom.SVGElement]
  • type Tag = TypedTag[dom.Element]

Both backends share a common structure defined in generic.Bundle, but they differ in how they handle the Builder and Output types.

Scalatags provides implicit conversions that allow you to pass standard Scala collections directly as children (modifiers) of a tag. This makes it easy to render lists of elements or handle optional elements without manual iteration.

Supported collections:

• Seq[A]
• Option[A]
• Array[A]
• geny.Generator[A] (via GeneratorFrag)

All elements within these collections must satisfy the Modifier or Frag requirements.

// Example: Passing a Seq of elements directly to a tag
val items = Seq(span("one"), span("two"))
div(items)

// Example: Passing an Option
val maybeSpan = Some(span("optional"))
div(maybeSpan)

A StyleTree is an intermediate structure representing a set of CSS rules before they are rendered into a final stylesheet. It consists of selectors (the CSS selector strings), styles (a map of property-value pairs), and children (nested StyleTree objects). The stringify method flattens this tree into standard CSS syntax, handling nesting and pseudo-selectors correctly.

// A StyleTree can be flattened into CSS via stringify
val tree = StyleTree(Seq(".cls1"), SortedMap("color" -> "red"), Nil)
val css = tree.stringify(Nil)
// Result: .cls1 {
//   color:red
// }