morpheus

README

Morpheus

Morpheus is an open alpha web component UI kit. It provides 48 components and 5 utility components, and targets server-driven architectures.

Install

Three static assets: the base stylesheet, one theme stylesheet, and the component bundle. jsDelivr serves every tagged release straight from this repository.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/romshark/morpheus@v0.1.0/min/morpheus.css"/>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/romshark/morpheus@v0.1.0/min/theme-default.css"/>
<script type="module" src="https://cdn.jsdelivr.net/gh/romshark/morpheus@v0.1.0/min/bundle.js"></script>

Pin the tag. Floating refs such as @latest resolve to the newest matching tag, so they pull in breaking changes. To self-host, take the same files from /min/ or from a release.

The Go module carries the templ wrappers (neo.Select, datastar.ComboboxAsync, and one per component):

go get github.com/romshark/morpheus

See Getting started for the walkthrough.

Motivation

Morpheus targets a server-centric stack of Go, Templ, and Datastar. basecoatui covers much of this stack but has limits: its combobox cannot be patched from the server without corrupting internal JavaScript state, a fix that has been on its roadmap for some time.

Morpheus is a proof of concept of a web component UI kit that is easy to patch from the server through what Datastar calls "fat morphs": a single page template is re-rendered and the HTML is sent over SSE to be morph-patched onto the existing DOM. It is designed from scratch for server-driven architectures, with other use cases in mind. Morph-based patching also exists in other ecosystems, such as:

• Alpine.js morph plugin
• HTMX Idiomorph extension
• Hotwire Turbo
• Laravel Livewire.

For the architecture and the reasoning behind these choices, see DESIGN.md.

Browser support

Morpheus targets Baseline Newly available as of August 2024. Minimum versions:

Browser	Minimum
Chrome / Edge	125
Safari	17.5
Firefox	129

There is no polyfill layer and no legacy fallback path. The kit uses the platform directly, and these features set the floor:

• @starting-style and transition-behavior: allow-discrete: enter and exit animations for surfaces that toggle display.
• :state() and CustomStateSet: a component's internal state, kept out of the light DOM so a morph cannot strip it (see Internal state).
• Popover API and <dialog>: top-layer rendering, modal lifecycle, and light dismiss.
• :has(), container queries, and round(): layout and sizing that reacts to content and to the parent box rather than the viewport.

Two features degrade instead of setting the floor: scrollend falls back to a settle timer where it is missing, and :host-context() (Chromium and WebKit only) carries an increased-contrast refinement that Firefox skips.

Developing

Prerequisites:

• Go (minimum version in go.mod)
• Templ
• golangci-lint
• Templier
• Node.js (for esbuild).

Commands:

• make gen: full build (install js deps, bundle JS/CSS, run templ generate, render the static site into ./dst).
• make watch: incremental rebuilds with live-reload via templier.
• make bundle-size: report raw/gzip/brotli sizes of the shippable JS + CSS.
• make clean: remove ./dst and generated bundles.

See CONTRIBUTING.md for the contribution workflow.

FAQ

See FAQ.md.