Skip to content

Commit

Permalink
Docs: Elaborate on missing keys
Browse files Browse the repository at this point in the history
  • Loading branch information
raquo committed Nov 18, 2024
1 parent 14d4dfa commit 371fc8d
Showing 1 changed file with 15 additions and 0 deletions.
15 changes: 15 additions & 0 deletions website/docs/documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -486,13 +486,16 @@ If that is what you wanted, that's fine, Laminar will not break, it's just weird

### Missing Keys

What do you do if you want to use a less-popular HTML attribute or prop that Laminar does not (yet) have? How do you define custom attributes, custom html props, styles, etc.?

Laminar gets the definition of HTML and SVG DOM tags, attributes, properties, events and CSS styles from [Scala DOM Types](https://github.com/raquo/scala-dom-types). These definitions provide hundreds of keys, but they are not exhaustive. For example, we don't have CSS grid properties like `grid-area` defined, so those are not available to be put on the left hand side of `:=` methods.

To work around this, you can contribute definitions of missing attrs / props / etc. to Scala DOM Types. It's easy – you don't even need to code any logic, just need to specify the names and types of the things you want to add. For example, the `value` property is defined at the bottom of [PropDefs.scala](https://github.com/raquo/scala-dom-types/blob/master/shared/src/main/scala/com/raquo/domtypes/defs/props/PropDefs.scala). Read [this](https://github.com/raquo/scala-dom-types/#reflected-attributes) to understand the difference between props and attributes and reflected attributes.

Alternatively, you can define the keys locally in your project in the same manner as Laminar does it, for example:

```scala
import com.raquo.laminar.codecs.*
val superValue: HtmlProp[String] = htmlProp("superValue", StringAsIsCodec) // imaginary prop
val onTouchMove: EventProp[dom.TouchEvent] = eventProp("touchmove")

Expand All @@ -506,6 +509,18 @@ And similarly with `styleProp`, `htmlAttr`, `htmlTag`, `svgAttr`, `svgTag`.

I mentioned `onTouchMove` as an example, but you don't have to do this for touch events specifically, because [@felher](https://github.com/felher) already [added](https://github.com/raquo/scala-dom-types/pull/102) them to address this particular shortcoming. Unless you want touch events regardless of that, in which case, you're welcome to it.

Some more examples of real attrs / props (that may already exist in Laminar):

```scala
import com.raquo.laminar.codecs.*

val tabIndex: HtmlProp[Int, Int] = htmlProp("tabIndex", IntAsIsCodec) // https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/tabIndex

val asyncAttr: HtmlAttr[Boolean] = htmlAttr("async", BooleanAsAttrPresenceCodec) // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#async

val decodingAttr: HtmlProp[String, String] = htmlProp("decoding", StringAsIsCodec) // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#decoding
```


### Modifiers FAQ

Expand Down

0 comments on commit 371fc8d

Please sign in to comment.