Skip to content

Getting Started

Jump to bottom
manolo edge edited this page Jul 6, 2025 · 20 revisions

Welcome to Cardboard.js! This guide will walk you through the basics of setting up your environment, creating your first elements, and understanding core concepts. Cardboard.js allows you to build web applications using only JavaScript or TypeScript, saying goodbye to writing HTML and CSS files directly.

Table of contents

Installation

npm install @nkeff/cardboard-js

↑ Go to top

Importing Cardboard.js

How you import Cardboard.js depends on your project setup.

As an ES Module

If you're working in a project with a build system or native ES module support:

// Typically from node_modules if it were published
import { tag, init, allTags, p, div /*, etc. */ } from '@nkeff/cardboard-js';

As a Script Tag in HTML

For quick experiments or simpler setups, you can include the bundled file. Make sure the path to cardboard.bundle.js is correct for your project structure after installation.

Global:

<script src="https://cdn.jsdelivr.net/npm/@nkeff/cardboard-js/dist/cardboard.global.js"></script>
<script>
  // Cardboard will be available as a global object
  const { div, p, button } = Cardboard.allTags;
  // Now you can use div(), p(), button(), etc.
</script>

Module:

<script src="https://cdn.jsdelivr.net/npm/@nkeff/cardboard-js/dist/cardboard.global.js"></script>
<script>
  import { tag, init, allTags, p } from 'https://cdn.jsdelivr.net/npm/@nkeff/cardboard-js/dist/cardboard.js';
  // Now you can use div(), p(), button(), etc.
</script>

↑ Go to top

Initializing Your Application

Before you can add any elements to the page, Cardboard.js needs to be initialized. The init() function does this for you.

import { init, p, allTags } from '@nkeff/cardboard-js'; // Adjust path as needed
const { div } = allTags;

// Initializes Cardboard and mounts to document.body by default
const root = init();

// Now you can append elements to the root
root.append(
  p('Hello, Cardboard.js!'),
  div('This is a div element.')
);
  • init() sets up Cardboard and by default, creates a root tag that references the <body> of your HTML document.
  • You can specify a different root element: init({ root: '#my-app-container' }).

Important: Using init() is crucial for Cardboard.js to function correctly.

Tip for Cleaner Code: Destructure allTags to easily access tag creation functions:

const { div, p, span, button, input, style, a, hr } = allTags;

↑ Go to top

Creating and Manipulating Elements

Cardboard.js provides functions for all standard HTML tags. Once an element (or "tag") is created, you can easily manipulate its properties.

Creating Elements

Simply call the function corresponding to the HTML tag you want:

const myParagraph = p('This is a paragraph.');
const myButton = button('Click Me');

↑ Go to top

Adding Classes and Styles

import { init, div, allTags } from '@nkeff/cardboard-js'; // Adjust path
const { p } = allTags;

const root = init(); // Ensure Cardboard is initialized

const styledDiv = div()
  .addClass('main-content', 'highlighted')
  .addStyle('color', 'blue')
  .addStyle('fontSize', '16px');

const styledParagraph = p('Styled text.')
  .addStyle({
    fontWeight: 'bold',
    padding: '10px',
    border: '1px solid green'
  });

// Append them to the root (or another mounted tag)
root.append(styledDiv, styledParagraph);

❕Note: While you can use inline styles (tag.addStyle, tag.setStyle, etc...), like in HTML, use them sparely as it might lead to performance issues. If the styles are going to be used multiple times, consider adding a style block to the head. ↑ Go to top

Setting Attributes

import { init, input, allTags } from '@nkeff/cardboard-js'; // Adjust path
const { img } = allTags;

const root = init(); // Ensure Cardboard is initialized

const myInput = input()
  .addAttr('type', 'text')
  .addAttr('placeholder', 'Enter your name');

const myImage = img()
  .addAttr('src', '/path/to/image.jpg') // Replace with an actual image path
  .addAttr('alt', 'A descriptive alt text');

root.append(myInput, myImage);

For a full guide, see Tag Manipulation. ↑ Go to top

Using Mount Points

Mount Points offer a flexible way to control where new elements are added to the DOM, without needing to pass parent elements around explicitly.

NOTICE: Mount Points are a powerful feature, but their API might evolve. For the latest discussions, see issue #37.

Setting a Mount Point

The mountPoint() function sets the "current parent." Any tags subsequently mounted using the <tag>.mount() method will become children of this parent.

Using an existing element (e.g., body or a div selected by ID):

import { init, mountPoint, tag, allTags } from '@nkeff/cardboard-js'; // Adjust path
const { p } = allTags;

init(); // Initializes Cardboard

// Set the document body as the mount point
mountPoint(tag('body')); // You can also use selectors like tag('#my-existing-div')

p.mount("I'm a child of the body.");

Using a newly created Cardboard tag as a mount point:

import { init, mountPoint, getMountPoint, allTags } from '@nkeff/cardboard-js'; // Adjust path
const { p, div } = allTags;

init();

const container = div().setId('my-container');
container.mount(); // Add container to the current mount point (e.g., body)
mountPoint(container); // Now, 'container' is the new current parent

p.mount("I'm a child of the 'my-container' div.");

// You can also use getMountPoint() to interact with the current mount point
getMountPoint().append(p("I'm also a child of 'my-container'."));
  • The <tag>.mount() method on a tag builder adds it to the current mount point.
  • mountPoint(someTag) sets someTag to be the current mount point. ↑ Go to top

Nesting and Switching Mount Points

You can change the mount point as needed, and use restoreMountPoint() to go back to the previous one. This is useful for building nested structures.

import { init, mountPoint, restoreMountPoint, allTags } from '@nkeff/cardboard-js'; // Adjust path
const { div, p } = allTags;

const rootTag = init(); // Initial mount point is 'rootTag' (e.g. body)

const wrapper = div("I'm the main wrapper");
wrapper.mount(); // Mount wrapper to rootTag
mountPoint(wrapper); // Set wrapper as the current mount point

const childDiv = div("I'm inside the wrapper");
childDiv.mount(); // Mount childDiv to wrapper
mountPoint(childDiv); // Set childDiv as the current mount point

p.mount("I'm inside the child div!"); // Mount p to childDiv

restoreMountPoint(); // Current mount point is now 'wrapper' again
p.mount("I'm back inside the wrapper!"); // Mount p to wrapper

restoreMountPoint(); // Current mount point is now 'rootTag' again
p.mount("I'm at the root level now!"); // Mount p to rootTag

Learn more in the Mount Points Guide. ↑ Go to top

Building a Simple Component with State

Cardboard.js includes a simple state management system. Here's how to build a basic counter component:

import { init, state, button, allTags } from '@nkeff/cardboard-js'; // Adjust path
// const { button } = allTags; // Or import directly if you prefer

const root = init();

// Define a reactive state variable
const count = state(0);

// Create a component (a function that returns a tag)
const Counter = () => {
  return button()
    .text(`Clicked $count times`, { count }) // Text updates when count changes
    .addStyle('color', 'purple')
    .addClass('clicker-button')
    .clicked(() => count.value++); // Update state on click
};

// Add the component to the page
root.append(Counter());

This example demonstrates:

  • Creating a state variable.
  • A function Counter that returns a UI element (button).
  • Reactive text (using a template string and providing the state object) that updates when count.value changes.
  • An event handler (.clicked()) that modifies the state.

Explore more about State and Reusable Components. ↑ Go to top

Next Steps

You've now seen the basics of Cardboard.js! To dive deeper, check out these resources:

This Wiki is a work in progress, and your help is greatly appreciated!

If you have some free time and are interested in contributing to the wiki or the project in general, please don't hesitate to reach out. All contributions are welcome!

Cardboard

Dip your toes

Up to the waste!

Develop

Clone this wiki locally