Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGES.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# 0.17.0

* Support custom `data-*` attributes in DOM JSX, including optional string values (@anmonteiro in https://github.com/reasonml/reason-react/pull/933)
* Upgrade `ppxlib` lower bound to `0.36` (@anmonteiro in https://github.com/reasonml/reason-react/pull/883)
* Remove `fomat` from ReactDOM's props (@davesnx in https://github.com/reasonml/reason-react/pull/929)
* Fix typo on `onEncrypted` (@davesnx in https://github.com/reasonml/reason-react/pull/930)
Expand Down
80 changes: 69 additions & 11 deletions docs/adding-data-props.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,79 @@
title: Adding data-* attributes
---

Reason doesn't support using props with dashes right now, ie: `data-id` or `data-whatever`. You can overcome this by creating a `Spread` component:
DOM JSX accepts custom data attributes as camelCase props:

```reason
/* Spread.re */
[@react.component]
let make = (~props, ~children) => React.cloneElement(children, props);
let element = <div className="item" dataTestId="item-42" dataState="ready" />;
```

Using Spread:
The rendered element has `data-test-id="item-42"` and `data-state="ready"`.
This works on both HTML and SVG elements.

## Values

Data attribute values have type `string`. They can be literals or expressions:

```reason
let itemId = 42;
let element = <div dataItemId={Int.to_string(itemId)} />;
```

Pass an `option(string)` with `=?` to make an attribute optional. `Some(value)`
sets the attribute, and `None` omits it:

```reason
[@react.component]
let make = () =>
<Spread props={"data-cy": name}>
/* This div will now have the `data-cy` attribute in the DOM! */
<div />
</Spread>;
let render = (state: option(string)) => <div dataState=?state />;

let ready = render(Some("ready"));
let absent = render(None);
```

## Attribute names

Uppercase letters become lowercase, with hyphens at word boundaries. Acronyms
stay together, digits stay attached to the preceding word, and underscores are
preserved:

| JSX prop | DOM attribute |
| --- | --- |
| `dataTestId` | `data-test-id` |
| `dataURLPath` | `data-url-path` |
| `dataVersion2` | `data-version2` |
| `dataFoo_bar` | `data-foo_bar` |
| `dataFoo_Bar` | `data-foo_bar` |
| `dataFoo__bar` | `data-foo__bar` |
| `data_foo` | `data_foo` |
| `datafoo` | `datafoo` |

The standard `data` and `datatype` props keep their existing meanings. Other
props beginning with `data` follow the conversion above. Names containing
apostrophes are rejected because they are invalid DOM attribute names.

Each attribute name can occur only once on an element. Repeating a prop or
using two props that produce the same name is a compile-time error, even when
an optional value is `None`:

```reason
/* Rejected: both props render as data-url. */
let element = <div dataURL="first" dataUrl=?None />;
```

`dataFoo` and `data_foo` are distinct: they produce `data-foo` and `data_foo`.

## Component props

The name conversion applies to DOM elements. Props on your own components keep
their declared names and types. Convert values when forwarding them to the DOM:

```reason
module Item = {
[@react.component]
let make = (~dataId: int) => <div dataId={Int.to_string(dataId)} />;
};

let element = <Item dataId=42 />;
```

Ordinary DOM props such as `className`, `onClick`, and `ref` retain their usual
type checks when used alongside data attributes.
3 changes: 3 additions & 0 deletions docs/jsx.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,9 @@ Which compiles to
React.createElement('div', {})
```

DOM elements also support custom [`data-*` attributes](adding-data-props.md),
written as camelCase props such as `dataTestId`.

## Capitalized

```reason
Expand Down
Loading
Loading