executable_html

v3.1.6

Published

3 months ago

Build interactive surveys, questionnaires, and experiments using just HTML custom elements.

0High
0Medium
0Low

b3008

web-components custom-elements survey questionnaire experiment declarative html lit likert form interactive

Executable HTML

Build interactive surveys, questionnaires, and experiments using just HTML.

Executable HTML is a library of custom web components that turn static markup into interactive, sequential experiences. Instead of writing JavaScript to manage state, control flow, and data collection, you describe your entire application declaratively with HTML tags.

Live Documentation & Examples | npm | GitHub

Why?

Building surveys and experiments typically requires wiring up JavaScript for page flow, branching logic, data collection, and storage. Executable HTML replaces all of that with a declarative HTML vocabulary:

No JavaScript required for standard survey flows
Branching and conditionals via <aa-choose> / <aa-when> / <aa-otherwise>
Automatic data collection through <aa-session> and localStorage
Rich form controls — sliders, Likert scales, multiple choice, text input, affect grids
Progressive enhancement — enhanced UI when Web Awesome is loaded, native fallbacks otherwise

Quick example

<aa-session name="my-survey">
  <aa-sequence>
    <aa-screen submit-button-text="Next">
      <aa-label>How are you feeling?</aa-label>
      <aa-slider name="mood" min="0" max="100"
        min-label="Bad" max-label="Great">
      </aa-slider>
    </aa-screen>
    <aa-screen submit-button-text="Done">
      <aa-label>Thank you!</aa-label>
    </aa-screen>
  </aa-sequence>
</aa-session>

Installation

npm install executable_html

import "executable_html";

All custom elements are automatically registered. Just write HTML.

Components

Session & data

aa-session — Top-level container that manages memory and data collection
aa-variable — Declares a named variable with a value
aa-memory — Underlying storage layer (localStorage)

Control flow

aa-sequence — Executes child elements one after another
aa-choose / aa-when / aa-otherwise — Conditional branching based on expressions
aa-jump — Jump to a named step within a sequence

User interface

aa-screen — A page/step with a submit button that collects values
aa-label — Display text
aa-slider — Numeric slider input
aa-multiple-choice / aa-choice-item — Single-select choice
aa-checkboxes — Multi-select checkboxes
aa-text-answer — Free text input
aa-likert-scale — Likert scale rating
aa-affect-grid — 2D affect/emotion grid

Utilities

aa-function-random — Generate random values
aa-geolocation — Capture device location

Styling

Components are styled using CSS custom properties and ::part() selectors:

/* Override the default font */
:root {
  --aa-font-family: "Inter", sans-serif;
}

/* Style the submit button */
aa-screen::part(button) {
  background: #4f46e5;
  border-radius: 8px;
}

See the Storybook documentation for the full list of CSS custom properties per component.

TypeScript

Types are exported for all public classes and event detail interfaces:

import type { AASession, AASessionInput } from "executable_html";

Browser support

Requires browsers with support for:

Custom Elements v1 (all modern browsers)
ES2020 (Chrome 80+, Firefox 80+, Safari 14+, Edge 80+)

No polyfills are included or required for modern browsers.

Development

npm run dev          # Vite dev server with getting-started example
npm run storybook    # Storybook documentation and playground
npm test             # Unit tests (web-test-runner)
npm run test:e2e     # End-to-end tests (Playwright)

See CONTRIBUTING.md for more details.

License

MIT