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.

Further reading

• Live documentation (Storybook)
• Paper: rationale and motivation
• Paper: implementation
• Changelog

License

MIT