Scala DOM Types
"com.raquo" %% "domtypes" % "<version>" // JVM & SBT "com.raquo" %%% "domtypes" % "<version>" // Scala.js 1.14.0
Scala DOM Types is used by the following Scala.js UI libraries:
As well as by:
- Scala DOM Test Utils, a library that verifies that your DOM node / tree matches the spec
As the end-user of these libraries, you do not depend on Scala DOM Types at runtime, those libraries use it at their compile time (for SDT v17.0.0+).
Table of Contents
- Why use Scala DOM Types
- What about ScalaTags
- What about scala-js-dom
- Design Goals
- Related Projects
Please use Github issues for bugs, feature requests, as well as all kinds of discussions, including questions on usage and integrations. You can watch this project on Github to get issue updates if you're interested in following discussions.
Q: I want to add an element tag / attribute / prop / etc.
A: Awesome! It might seem daunting the first time, but it's not hard. Here's how to add a new key (i.e. tag / property / attribute / event / etc.):
Confirm that it's reasonably well supported by browsers. Support by latest Firefox and Chrome is the bare minimum. example.
If it's a property or an attribute, figure out whether it's: (a) non-reflected attribute, (b) non-reflected property, or (c) reflected property. The latter are pretty common. Read the MDN docs, read the docs below, and see other reflected properties we defined for reference.
If applicable, figure out the type of values that this attribute / property / etc. accepts, or the type of events that it fires. See MDN docs for that. Note that we only care about the type that we can write into it, not the type we can read from it (the latter often includes
js.undefined). See what codec(s) our other properties of the same type use, it's probably an "as-is" codec like StringAsIsCodec. See the docs on codecs below.
Figure out what the new key should be called, according to the naming convention documented below.
You now have enough information to easily test your understanding. For Laminar, try using
eventProp/ etc. locally as suggested here. For example:
styleProp("gap") := "20px". For other UI libraries using Scala DOM Types, see their docs.
If everything is looking good, you can now add the information necessary to create an SDT definition for this key. Add it to one of the traits in the shared/main/.../defs folder. Look at how other keys are done, and follow the lead. CSS props require a bit more annotation than others. Look at our defs for other CSS props of the same type to see which
sbt testbefore committing. This will make a few sanity checks, and generate sample code found in js/test/.../defs. You should commit that generated code too.
And that's it. Send this PR, and I'll check everything (make sure to provide links to MDN docs!). You are not blocked by SDT releases – just keep using the temporary syntax from step 6 until the thing you've added to SDT lands in Laminar / Calico / etc.
If this is too much for you right now, or if you're not sure about something, open an issue or ask on Laminar discord.
Why use Scala DOM Types
Canonical use case: you're writing a Scala or Scala.js library that does HTML / DOM construction / manipulation and want to provide a type-safe API like this:
div( zIndex := 9000, h1(rel := "title", "Hello world"), p( backgroundColor := "red", "Welcome to my fancy page!", span(draggable := true, "Fancyness is important.") ), button(onClick := doFancyThing, "Do Fancy Thing"), a(href := "http://example.com", title := "foo", "Example") )
Of course, your API doesn't need to look anything like this, that's just an example. Scala DOM Types doesn't actually provide the
:= methods that you'd need to make this example work.
If you do in fact want to create similar syntax, see guidelines for library authors below.
What about ScalaTags
ScalaTags is a popular Scala library that contains DOM type definitions similar to what we have here. However, Scala DOM Types is different in a few ways:
More type safe. For example, in Scala DOM Types an
inputtag is linked to Scala.js
HTMLInputElementclass. This lets you provide exact types for the DOM nodes you create, so that you don't need to perform unsafe casts in your application code if you want to e.g. access the
valueproperty on an
inputyou created. Similarly, all attributes, properties and styles are linked to the types that they accept to prevent you from assigning incorrect values.
More flexible. Scala DOM Types does not tell you how to define your attributes / props / styles / tags, or how to compose them together, and does not enforce any rendering paradigm. You are free to implement your own composition. I see that some projects fork ScalaTags just to get the type definitions without everything else. Scala DOM Types does not get in your way, eliminating the need for such forking.
Better representation of native DOM types. Scala DOM Types handles Reflected Attributes consistently, and uses Codecs to properly encode/decode DOM values.
There are some other differences, for example Scala DOM Types uses camelCase for attr / prop / style names because that is consistent with common Scala style.
What about scala-js-dom
HTMLInputElement. You can use those types when you already have instances of DOM elements, but you can not instantiate those types without using untyped methods like
On the other hand, Scala DOM Types lets the consuming library create a type-safe representation of real JS DOM nodes or trees, and it is up to your library's code to instantiate real JS nodes from the provided description.
Oh, and Scala DOM Types does work on the JVM. Obviously you can't get native JS types there, but you can provide your own replacements for specific Scala.js types, or just not bother with such specificity at all.
The purpose of Scala DOM Types is to become a standard DOM types library used in Scala.js projects.
The most important type information must be encoded as Scala types. For example, DOM properties that only accept integers should be typed as such.
Reasonably Precise Types
The types we provide will never be perfect. For example, MDN has this to say about the
The value must be the id of a element in the same document. [...] This attribute is ignored when the type attribute's value is hidden, checkbox, radio, file, or a button type.
A far as I know, encoding such constraints as Scala types would be very hard, if it's even possible at all.
This is not to say that we are content with the level of type safety we currently have in Scala DOM Types. Improvements are welcome as long as they provide significantly more value than burden to users of this library. This kind of thing is often subjective, so I suggest you open an issue for discussion first.
Scala DOM Types is a low level library that is used by other libraries. As such, its API should be unopinionated and focused solely on providing useful data about DOM elements / attributes / etc. to consuming libraries in a way that is easy for them to implement.
We achieve this with a code generation approach. Instead of providing Scala traits in a predefined format, we give you tools to generate such traits in your own library, with your desired data structures, types, naming conventions, etc.
You can also use the raw element / attribute / etc. data contained Scala DOM Types yourself, whether at compile time or at runtime.
Sanity Preservation Measures
We should provide a better API than the DOM if we can do that in a way that keeps usage discoverable and unsurprising.
Developers familiar with the DOM API should generally be able to discover the names of attributes / tags / etc. they need using IDE autocompletion (assuming they expect the names to match the DOM API). For example:
forId is a good name for the
for attribute. It avoids using a Scala reserved word, and it starts with
for like the original attribute, so it's easy to find. It also implies what kind of string is expected for a value (an
id of an element).
Within that constraint, we should also try to clean up the more insane corners of the DOM API.
- For example, the difference between
valueproperty trips up even experienced developers all the time. Scala DOM Types on the other hand has a
defaultValuereflected attribute and a
valueproperty, which behave the way everyone would expect from the given names or from their knowledge of the DOM API.
- For another example, enumerated attributes like
contentEditablethat in the DOM accept "true" / "false" or "on" / "off" or "yes" / "no" should be boolean attributes in Scala DOM Types.
All naming differences with the DOM API should be documented in the README file (see below). Type differences are generally assumed to be self-documenting.
How to Use Scala DOM Types in Your Library
You generally don't want to use Scala DOM Types directly as the end-user. If you just want to generate some HTML on the backend or something similarly simple, you might want to use ScalaTags instead, or create a new library for that based on Scala DOM Types using the guide below.
So, you're building a DOM manipulation library such as Laminar, Outwatch or ScalaJS-React (the former two use Scala DOM Types, the latter doesn't). This guide focuses on the Scala.js use case. Scala DOM Types is perfectly usable from the backend as well, but it will need more customization.
First off, if you're building such a library, you need to know quite a few things about how JS DOM works. Scala DOM Types is just a collection of type information, it's not an abstraction layer for the DOM. You're building the abstraction layer. We can't cover everything about JS DOM here, but we will touch on some of the nastier parts in the following sections.
Look at MouseEventPropDefs in Scala DOM Types – several of such listings contain all the data that this library offers. This particular file lists all the mouse-related events that you can handle in the DOM. We create such listings manually. See discussion in #87 and #47 for why we don't generate these listings from some official source.
The data in
MouseEventPropDefscan be used as-is in certain cases, but typically we want to transform it into well typed Scala traits that look like GlobalEventProps. In fact, prior to #87, such typed traits were the only format in which Scala DOM Types offered its data. For example, here's the old MouseEventProps from Scala DOM Types version 0.16.0-RC3. As you can see, to make such a trait flexible enough for different libraries and runtimes, we had to use a lot of type params – not ideal, especially for end users who just want to see e.g. the type of events a certain key produces.
The new version of Scala DOM Types relies on code generation to produce simple abstraction-free traits like GlobalEventProps, tailored for a specific UI library like Laminar. That
GlobalEventPropsfile was in fact produced by this code generator as part of Scala DOM Types GeneratorSpec test, and its output is verified in CompileSpec.
Previously, Scala DOM Types offered highly abstracted traits as a runtime dependency of libraries like Laminar. Now, Laminar uses Scala DOM Types at compile time only, generating similar traits at compile time.
In Laminar, the code generation is done in DomDefsGenerator. As you see, the generator is customized with the names of Laminar's own types, package names, and desired folder structure. See Laminar's build.sbt and project/build.sbt for the compile-time generator build setup.
You will need to create a similar generator setup for your library.
There are several ways to customize Scala DOM Types code generation. Simpler ones first:
Provide different params to
Provide different params to
(Including by transforming the list of defs that you pass to them)
TraitGeneratorsubclasses manually instead of calling
*TraitGeneratorclasses, and override their methods
Create your own generator, perhaps by extending
Typical usage of Scala DOM Types should not require overly-involved customization effort. If your Scala.js use case seems unnecessarily hard to achieve, please let me know.
Provide the keys that are deliberately missing from Scala DOM Types
We deliberately do not include a small set of "complex" keys that UI libraries tend to have different opinions about, such as the
styleHTML attributes. See the full list below. Your library needs to provide such keys itself, for example see ComplexHtmlKeys and ComplexSvgKeys in Laminar – those are not generated, but manually created.
Provide the Codecs. These are used to translate between Scala values and DOM values. See codecs in Laminar. Your implementation will be almost identical, depending on whether you talk to the DOM directly or via some virtual DOM library with special needs. See below for more info on the codecs.
Provide concrete types for Tags, Attributes, etc., as well as their functionality (
:=methods, etc.). The type representing StyleProp should extend the
GlobalKeywordsgenerated style trait, or provide those keywords in some other way.
Finally, create "the bundle". You've generated a bunch of well typed traits and created concrete types – now you need to instantiate a single object that will extend all those traits to expose all the keys like
onClick, etc. The actual implementation of this might vary based on your preferences and on how you configured the generator, but you can refer to the top of the Laminar.scala file. As you see, I separate HTML keys from SVG keys and ARIA keys to avoid name collisions and to reduce IDE autocomplete pollution. You can choose to do this differently, but that will require some customization on your part.
With the generator, you're adding comments derived from MDN content into your project – those comments are licensed under the CC-BY-SA license, so you need to add a corresponding notice to your project file (or customize code generation to not include the comments for every key). See the bottom of this README.
Migrating to code generation from an older version of Scala DOM Types
Follow the guide above to set up a generator in your project as explained above
There is no built-in support for
TypeTargetEventanymore – just native JS types.
You can implement / customize that in your project if you wish, but this isn't useful enough IMO.
CSS styles now have support for unit helpers – e.g. extensions like
width.calc("20px + 10%"), however you need to implement all that behaviour, and copy-paste the unit traits into your code – see the units in Laminar for example.
HTML attributes and DOM properties are different things. As a prerequisite for this section, please read this StackOverflow answer first.
For more on this, read Section 2.6.1 of this DOM spec. Note that it uses the term "IDL attributes" to refer to what we call "DOM properties", and "Content attributes" to refer to what we here call "HTML attributes".
So with that knowledge,
id for example is a reflected attribute. Setting and reading it works exactly the same way regardless of whether you're using the HTML attribute
id, or the DOM property
id. Such reflected attributes live in
ReflectedHtmlAttrs trait, which lets you build either attributes or properties depending on what implementation of
ReflectedHtmlAttrBuilder you provide.
To keep you sane, Scala DOM Types reflected attributes also normalize the DOM API a bit. For example, there is no
value attribute in Scala DOM Types. There is only
defaultValue reflected attribute, which uses either the
value HTML attribute or the
defaultValue DOM property depending on how you implement
ReflectedHtmlAttrBuilder. This is because that attribute and that property behave the same even though they're named differently in the DOM, whereas the
value DOM property has different behaviour (see the StackOverflow answer linked above). A corresponding HTML attribute with such behaviour does not exist, so in Scala DOM Types the
value prop is defined in trait
Props. It is not an attribute, nor is it a reflected attribute.
Reflected attributes may behave slightly differently depending on whether you implement them as props or attributes. For example, in HTML5 the
cols reflected attribute has a default value of
20. If you read the
col property from an empty
<textarea> element, you will get
20. However, if you try to read the attribute
col, you will get nothing because the attribute was never explicitly set.
Scala DOM Types provides some normalization of the native HTML / DOM API, which is crazy in places.
For example, there are a few ways to encode a boolean value into an HTML attribute:
- As presence of the attribute – if attribute is present,
- As string "true" for true, or "false" for false
- As string "yes" for true, or "no" for false.
Which one of those you need to use depends on the attribute. For example, attribute
disabled needs option #1, but attribute
contenteditable needs option #2. And then there are DOM Properties (as opposed to HTML Attributes) where booleans are encoded as actual booleans.
Similarly, numbers are encoded as strings in attributes, with no such conversion when working with properties.
For example, the codecs for the three boolean options above are
Scala DOM Types provides a reference implementation of the codecs. Since you only use Scala DOM Types at compile time, you should copy-paste that implementation into your own library, instead of trying to load Scala DOM Types as a runtime dependency.
className often require special handling in consuming libraries. For example, instead of a
String based interface, you might want to offer a
Seq[String] based one for
className. Because there is little to standardize on, Scala DOM Types deliberately does not provide those keys anymore. You need to add them to your library manually.
List of complex keys:
Naming Differences Compared To Native HTML & DOM
Although each library using Scala DOM Types is free to generate whatever code it wants, we provide a canonical
scalaName for every key that we recommend using. It is sometimes different from the native DOM name (
Below are the
scalaName-s of the DOM attributes / props / etc. For the record, Laminar uses these names verbatim.
scalaNameidentifiers are camelCased for consistency with conventional Scala style, e.g.
datalistdomName translates to
Attributes & Props
valueattribute is named
defaultValuebecause native HTML naming is misleading and confusing (example)
- Note that the
valueproperty retains its name
- Note that the
checkedattribute is named
defaultCheckedfor the same reason
- Note that the
checkedproperty retains its name
- Note that the
selectedattribute is named
defaultSelectedfor the same reason
- Note that the
selectedproperty retains its name
- Note that the
htmlForproperty are available as reflected attribute
forIdfor consistency and to avoid Scala reserved word
idreflected attribute is named
stepAttrto free up good names for end user code
nameattribute is named
nameAttrto free up a good name
resultSVG attributes are named
resultAttrrespectively to free up good names for end user code
loadingreflected HTML attribute is named
loadingAttrto avoid using a good name
contentattribute is named
contentAttrto avoid using a common name
formattribute is named
formIdto avoid conflict with
labelattribute is named
labelAttrto avoid conflict with
heightattribute is named
heightAttrto avoid conflict with
widthattribute is named
widthAttrto avoid conflict with
listattribute is named
listIdfor clarity and consistency
contextmenuattribute is named
contextMenuIdfor clarity and consistency
CSS Style Props
contentprop is named
contentCssto avoid using a common name
- Many tag names have a "Tag" suffix, usually to free up good names for end user code, or avoid some conflict, e.g.:
tpeto avoid Scala reserved word
Certain special keys are not defined in Scala DOM Types, and are left for the consuming library to define. Of those, typically:
classattribute is named
classNameand aliased as
styleattribute is named
My Related Projects
- Laminar – Reactive UI library based on Scala DOM Types
Nikita Gazarov – @raquo
License and Credits
Scala DOM Types is provided under the MIT license.
Comments pertaining to individual DOM element tags, attributes, properties and event properties, as well as CSS properties and their special values / keywords, are taken or derived from content created by Mozilla Contributors and are licensed under Creative Commons Attribution-ShareAlike license (CC-BY-SA), v2.5.