Note

for the purposes of easy documentation, all examples will be written with the JSX syntax which is not supported in the javascript standard and must use a preprocessor such as tsc, babel, esbuild, etc. This is entirely optional and the tagstring syntax is also supported, meaning you do not need any build step whatsoever to use this. An example of JSX syntax looks like

return (
    <button on:click={() => this.counter++}>I have been clicked {use(this.counter)} times!</button>
);

Whereas the equivalent plain javascript would look like

return html `
    <button on:click=${() => this.counter++}>I have been clicked ${use(this.counter)} times!</button>
`;

Which one you choose to use comes down to personal preference, but remember that all examples shown with JSX work in plain javascript.

The Basics

In dreamland, everything is an HTML element. We try to abstract the DOM, but never replace it.

Let's create an HTML element right now.

let button = <button class="some-button">content here!</button>;
document.body.appendChild(button);

We just created a button, with the class "some-button", and added it to the document. This is the simplest possible way of using dreamland, and is why it's so easy to slowly transition to using it from a plain-js codebase.

Extra (syntax) Sugar!

What if we wanted to do something when the button is clicked? For any DOM event, you can use on: handlers.

let button = <button class="some-button" on:click={()=>alert("button clicked!")}>click me!</button>;