Phantom
A state—reactive DOM rendering engine for building UIs. 👻
npm i @sidiousvic/phantom
Phantom lets you build state—reactive UIs using raw HTML strings ejected from functions.
export default function Pizza(slices) {
return `
<div id="pizza-box">
<h1 data-phantom="${slices}" id="slices-h1">${slices}</h1>
</div>
`;
}
You update state via actions, and Phantom swaps DOM nodes for you.
phantomStore.fire({ type: "EAT_PIZZA" });
1. Create a Phantom store
Phantom will integrate with a Redux—like store to subscribe DOM rendering to state updates. Use createPhantomStore
to produce your store.
Show code ↯
import { createPhantomStore } from "@sidiousvic/phantom";
const data = {
slices: ["🍕", "🍕", "🍕"],
};
function reducer(state = data, action) {
switch (action.type) {
case "EAT_SLICE":
return { ...state, slices: state.slices.slice(0, -1) };
default:
return state;
}
}
const store = createPhantomStore(reducer);
export default phantomStore;
2. Write an entry Phantom component
Phantom components are functions that return HTML template strings. This allows you to inject dynamic data (including other components) via template literals ${}
.
We recommend the leet-html
VSCode extension for HTML template highlighting.
Show code ↯
function phantomComponent() {
return `
${Pizza()} // inject the Pizza component from above
`;
}
3. Initialize Phantom and appear()
Start the Phantom engine with the phantomStore
and a phantomElement
.
Show code ↯
import phantom from "@sidiousvic/phantom";
import phantomStore from "./phantomStore.js";
import Pizza from "./ui/Pizza.js";
const { fire, data, appear } = phantom(phantomStore, phantomComponent);
appear();
Phantom will then expose the methods fire
, data
and appear
.
fire
and data
are pointers to the phantomStore. You're welcome to call them from the store directly.
fire
takes an action and fires it through the store.
data
returns the current in—store data.
appear
will perform the initial DOM render on call, your UI's first apparition. 👻
Use data
to read state from the Phantom store.
function phantomComponent() {
const { slices } = data();
return `
${Pizza(slices)}
`;
}
Pass data as arguments to components, and use them in your HTML templating.
export default function Pizza(slices) {
return `
<div id="pizza-box">
<h1 data-phantom="${slices}" id="slices-h1">${slices}</h1>
</div>
`;
}
⚠️ Always bind stateful elements with the data-phantom attribute. |
---|
⚠️ Specify an id attribute for all elements. |
---|
Use fire
to dispatch an action and trigger a state update + re—render.
document.addEventListener("click", eatPizza);
function eatPizza(e) {
if (e.target.id === "slices-h1") {
fire({ type: "EAT_PIZZA" });
}
}
Why use Phantom ?
A baby panda dies every time you choose a 1MB+* industrial—level frontend package to code a pomodoro clock or a personal portfolio page. 🐼
Show rationale ↯
You don't drive to the corner store, but walking is overrated. Phantom is the bike you need.
🖍 Declarative
With Phantom, you can write markup in a declarative way ala JSX using raw HTML strings, and inject dynamic data using template literals—staying fully JS native.
🍕 Component—based
Phantom lets you divide your UI into components, abstracting markup into composable functions.
🧪 Reactive
The Phantom engine integrates with a store and subscribes to state updates. It swaps nodes when their data changes.
👩🏾🏭 Closer to the JS metal
Phantom only helps with DOM rendering. Listeners, effects, style manipulation, routing—the fun stuff—is still in your hands. 🙌🏼
No JSX, no complex API, no syntactic hyperglycemia.
* unpacked size of ReactDOM is 3MB. Vue is 2.98MB. Phantom is < 99 kB.
Does Phantom use a virtual DOM?
Show answer ↯
When a component's data changes, Phantom will re—render that node in the DOM by diffing its internal PseudoDOM, an object representation of the DOM.
Why should I always include the data-phantom
attribute in stateful elements?
Show answer ↯
In order for your element to be reactive to data changes, Phantom needs to know which nodes are bound to the updated data. Specifying a data-phantom="${yourData}"
attribute is a simple way to do that.
Why should I always include an id
attribute in stateful elements?
Show answer ↯
Two reasons, one practical, one technical:
I. Once you get into the habit, specifying id
s results in remarkably declarative markup. It encourages you to think about each element's specific function in the UI and also helps to easily identify it visually in the DOM tree.
II. id
is one of the mechanisms that the Phantom engine uses to detect which nodes to update.
Is Phantom XSS secure?
Show answer ↯
Yes. Phantom uses its internal phantomExorciser
to sanitize HTML strings before injecting them into the DOM.
Phantom is written and built using Typescript.
Scripts
Contributing
Phantom is maintained by @sidiousvic. He is always happy to welcome eager contributors to the project.
There are several examples you can run, each furnished with their own devServer
configuration.
Click on one of the images above to be taken to an online sandbox.
Devs who have cloned Phantom may use npm run example/[example name]
and navigate to the url that appears in their terminal.
Phantom is made with love and pepperoni by @sidiousvic