scratch-box

August 12, 2026 ยท View on GitHub

scratch-box is a form associated custom element web component wrapper around the "CUSTOM ANIMATED CHECKBOXES" codepen by Sara Soueidan.

Declarative Custom Element

This is the world's first visual web component, built with custom element features and Declarative Custom Element cede scripts. It is "code-free". In particular, it draws from the el-maker base class module package, only loading ("dependency injecting") those features that are actually used, as needed. It is entirely built with a static html file root.html and a JSON file el-maker.json. Editing JSON by hand is error-prone and doesn't lend itself to Typescript checking. To overcome this, the JSON file is built and managed from el-maker.mjs using command:

npm run build-el-maker

This watches for changes to the mjs file and automatically rebuilds the el-maker.json file.

Dual Mode

The root.html file mentioned above can actually be opened via a static file web server, and the basic functionality of the web component can already be demo'd. Nothing could be easier! All that's missing is some behind the scenes dynamic functionality as far as linking up to an HTML form, and the ability to pass in the checked value dynamically. [TODO -- support passing in via querystring].

SSR support

To use this web component, the root.html file needs to either be embedded in the HTML stream for the landing page, or (lazily) imported/streamed in. In the main demo page, we see a full-blown SSR example, including progressing switching from raw checkboxes with minimal styling to the scratch-box component, passing any edits made to the raw checkboxes to the scratch-box during hydration without skipping a beat.

This optional true SSR progressive enhancement support is made possible with the help of two additional, optional element enhancements -- soak-up and be-gone.

API Reference

View the custom element manifest for scratch-box.

To use from CDN:

<scratch-box imp-h="scratch-box/root.html">
    <span slot=labelTxt>Create demo</span>
</scratch-box>
<scratch-box>
    <span slot=labelTxt>Write article</span>
</scratch-box>
<scratch-box>
    <span slot=labelTxt>Exercise</span>
</scratch-box>
<script type="importmap">
{
    "imports": {
        "scratch-box/": "https://cdn.jsdelivr.net/npm/scratch-box@0.0.14/",
        "be-bound/": "https://esm.sh/be-bound@0.0.38/"
    }
}
</script>
<script type=module src=https://esm.sh/imp-h@0.0.4 crossorigin="anonymous"></script>
<script type=module src=https://esm.sh/xtal-element@0.0.636/index.js crossorigin=anonymous></script>

Viewing Demos Locally

  1. Install git
  2. Fork/clone this repo
  3. Install node.js
  4. Open command window to folder where you cloned this repo

  5. git submodule add https://github.com/bahrus/types.git types

  6. git submodule update --init --recursive

  7. npm install

  8. npm run serve

  9. Open http://localhost:8000/ in a modern browser