Photo by Cosmic Timetraveler on Unsplash
Please ask questions in the dedicated discussions repository, to help the community around this project grow ♥
Update if you're looking for something even smaller than neverland, don't miss µland!
import {Component, render, html, useState} from 'neverland';
const Counter = Component((initialState) => {
const [count, setCount] = useState(initialState);
return html`
<button onclick=${() => setCount(count + 1)}>
Count: ${count}
</button>`;
});
// basic example, show two independent counters
render(document.body, html`
<div>
A bounce of counters.<hr>
${Counter(0)} ${Counter(1)}
</div>
`);
As React Hooks were born to simplify some framework pattern, Neverland goal is to simplify lighterhtml usage, in a virtual component way, through the mighty dom-augmentor.
See what I did there? React components' hooks are based on virtual DOM while neverland's hooks are based on virtual components.
This library simulates Custom Elements, without needing polyfills, simply by passing zero, one, or more arguments to every desired components in each template literal hole.
// if you don't need hooks, you don't need to wrap components
const LinkLi = ({text, href}, highlighted) => html`
<li class=${highlighted}>
see <a href="https://github.com/WebReflection/neverland/blob/master/${href}">${text}</a>
</li>
`;
// some container with some click logic that uses hooks: $(wrap it)
const Links = $((items) => {
const [clicked, changeState] = useState(-1);
const onclick = useCallback(event => {
const li = event.target.closest('li');
changeState(
// changeState accordingly to the clicked index
[].indexOf.call(event.currentTarget.children, li)
);
}, []);
return html`
<ul onclick=${onclick}>
${items.map(
(item, i) => LinkLi(item, i === clicked ? 'highlight' : '')
)}
</ul>`;
});
// render components within an element
render(document.body, html`
List of links:
${Links([
{text: 'blog', href: 'www.blog.me'},
{text: 'bio', href: 'www.bio.me'},
])}
`);
Both html
and svg
renders are exposed via the neverland
module, and you must use the render
utility
All hooks are provided by augmentor, via dom-augmentor that takes care or injecting life-cycle DOM events when useEffect
is used.
createContext(value)
useImperativeHandle
This hook is strictly React oriented with no meaning in current dom-augmentor world.
const Comp = $(() => html...)
?Every time you wrap a component you grant yourself the used hooks within would run specifically for that component.
However, if you create an extra hook, or your callback doesn't return either html
or svg
result, you don't need to wrap it.
A simple rule of thumbs to know when a component should be wrapped or not is the following one:
html
or svg
templates tag literals?If the answer to both points is yes, then you should wrap the callback, otherwise, you most likely shouldn't.
This little thinking is currently needed due the fact there's no parsing or pre-processing in neverland, so that such wrapping cannot be done automatically for you, when needed.
You can still decide to wrap any callback that returns html
or svg
templates tag literals results, but that might have performance implication in larger projects.
Common ways via bundlers or CDNs:
const {neverland: $, render, html, useState} = window.neverland
through script with source https://unpkg.com/neverland
const {neverland: $, render, html, useState} = require('neverland')
import {neverland as $, render, html, useState} from 'neverland'
import {neverland as $, render, html, useState} from 'https://unpkg.com/neverland?module'
If you use a bundler you can simply install neverland
via npm or yarn.
It is also possible to use it in browsers via https://unpkg.com/neverland:
// you can import it in any scope
const {neverland, html, useState} = window.neverland;
const VirtualComp = neverland(...);
// or ...
const {neverland:$, html} = neverland;
const VirtualComp = $(...);
html.for(ref[, id])
or svg.for(ref[, id])
render
is mandatory, no more DOM nodes out of the boxneverland
named export