Skip to content

Commit c8d1b66

Browse files
committed
Add more details and examples to the readme
1 parent 2a9049e commit c8d1b66

1 file changed

Lines changed: 103 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 103 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Templates are parsed by the browser's HTML parser and cached, achieving minimal
1515

1616
## Syntax: Like JSX but more lit
1717

18-
The syntax is inspired by `lit-html`, but includes features familiar to anyone who works with JSX:
18+
The syntax is inspired by [lit-html], but includes features familiar to anyone who works with JSX:
1919

2020
- Rest spread: `<div ...${props}>`
2121
- Self-closing tags: `<div />
@@ -31,6 +31,7 @@ Here's some ergonomic features you get for free that aren't present in JSX:
3131
- HTML's self-closing tags: `<img src=${url}>`
3232
- Optional end-tags: `<section><h1>this is the whole template!`
3333
- Component end-tags: `<${Footer}>footer content<//>`
34+
-
3435
- Support for HTML comments: `<div><!-- don't delete this! --></div>`
3536

3637
## Project Status
@@ -52,13 +53,57 @@ npm i htm
5253
**To hotlink:**
5354

5455
```js
55-
import { html, render } from 'https://unpkg.com/htm?module'
56+
import htm from 'https://unpkg.com/htm?module'
57+
import { html, render } from 'https://unpkg.com/htm/preact?module'
58+
```
59+
60+
## Usage
61+
62+
Since `htm` is a generic library, we need to tell it what to "compile" our templates to.
63+
64+
The target should be a function of the form `h(tag, props, ...children)`, and can return anything.
65+
66+
```js
67+
// this is our hyperscript function. for now, it just returns an description object.
68+
function h(tag, props, ...children) {
69+
return { tag, props, children };
70+
}
71+
```
72+
73+
To use that `h()` function, we need to create our own `html` tag function by binding `htm` to our `h()` function:
74+
75+
```js
76+
import htm from 'htm';
77+
78+
const html = htm.bind(h);
79+
```
80+
81+
Now we have an `html()` template tag that can be used to produce objects in the format we created above.
82+
83+
Here's the whole thing for clarity:
84+
85+
```js
86+
import htm from 'htm';
87+
88+
function h(tag, props, ...children) {
89+
return { tag, props, children };
90+
}
91+
92+
const html = htm.bind(h);
93+
94+
console.log( html`<h1 id=hello>Hello world!</h1>` );
95+
// {
96+
// tag: 'h1',
97+
// props: { id: 'hello' },
98+
// children: ['Hello world!']
99+
// }
56100
```
57101

58102
## Example
59103

60-
Curious to see what it all looks like?
61-
Here's a working app! It's just an HTML file, there is no build or tooling. You can edit it with nano.
104+
Curious to see what it all looks like? Here's a working app!
105+
106+
It's a single HTML file, and there's no build or tooling. You can edit it with nano.
62107

63108
```html
64109
<!DOCTYPE html>
@@ -95,4 +140,58 @@ Here's a working app! It's just an HTML file, there is no build or tooling. You
95140

96141
How nifty is that?
97142

143+
Notice there's only one import - here we're using the prebuilt Preact integration since it's easier to import and a little bit smaller.
144+
145+
The same example works fine without the prebuilt version, just using two imports:
146+
147+
```js
148+
import { h, Component, render } from 'preact';
149+
import htm from 'htm';
150+
151+
const html = htm.bind(h);
152+
153+
render(html`<${App} page="To-Do's" />`, document.body);
154+
```
155+
156+
## Other Uses
157+
158+
Since `htm` is designed to meet the same need as JSX, you can use it anywhere you'd use JSX.
159+
160+
**Generate HTML using [vhtml]:**
161+
162+
```js
163+
import htm from 'htm';
164+
import vhtml from 'vhtml';
165+
166+
const html = htm.bind(vhtml);
167+
168+
console.log( html`<h1 id=hello>Hello world!</h1>` );
169+
// '<h1 id="hello">Hello world!</h1>'
170+
```
171+
172+
**Webpack configuration via [jsxobj]:** ([details here](https://webpack.js.org/configuration/configuration-languages/#babel-and-jsx))
173+
174+
```js
175+
import htm from 'htm';
176+
import jsxobj from 'jsxobj';
177+
178+
const html = htm.bind(jsxobj);
179+
180+
console.log(html`
181+
<webpack watch mode=production>
182+
<entry path="src/index.js" />
183+
</webpack>
184+
`);
185+
// {
186+
// watch: true,
187+
// mode: 'production',
188+
// entry: {
189+
// path: 'src/index.js'
190+
// }
191+
// }
192+
```
193+
98194
[Tagged Templates]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates
195+
[lit-html]: https://github.com/Polymer/lit-html
196+
[vhtml]: https://github.com/developit/vhtml
197+
[jsxobj]: https://github.com/developit/jsxobj

0 commit comments

Comments
 (0)