Installation

Oblyx ships as one npm package, oblyx: a stylesheet and a set of custom elements with no framework and no build step required to use them. Add a <link> and a <script> to any page, server-rendered or static, and the elements upgrade themselves as soon as the script runs.

pnpm install
pnpm --filter oblyx build

CDN

The zero-install path. No build step, no node_modules, works from a plain .html file:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/oblyx/dist/oblyx.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/oblyx/dist/oblyx.js"></script>

This is the ES module build: tree-shakeable by bundlers that do consume it, and the smaller of the two builds. It is the default for anything served over http:// or https://.

npm

For projects that bundle Oblyx alongside their own code:

npm install oblyx

Import from oblyx to register the custom elements, and reference oblyx/dist/oblyx.css the way your bundler expects stylesheets to be pulled in.

ESM versus IIFE

Oblyx ships two JavaScript builds from the same source: an ES module (oblyx.js) and a self-contained classic script (oblyx.iife.js). Same components, same CSS, different loading mechanism. Reach for the module build by default; reach for the IIFE build specifically when a page might be opened directly from disk.

The reason the IIFE build exists at all: Chromium refuses to run <script type="module"> when the page is opened over file://(a CORS error, origin 'null'). Safari and Firefox allow it, but Chromium does not. A saved .html file that someone opens by double-clicking needs the classic script tag instead:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/oblyx/dist/oblyx.css" />
<script src="https://cdn.jsdelivr.net/npm/oblyx/dist/oblyx.iife.js"></script>

Verified locally: the module build works over http:// and fails silently over file:// in Chromium as described; the IIFE build works in both.

The stylesheet

oblyx.css is not optional. The custom elements render plain, semantic markup and class names (.ox-btn, .ox-btn--primary, and so on). All of the actual visual styling, including layout-critical rules the overlay positioning components depend on, lives in the stylesheet, not in the component's own shadow DOM (there is none: Oblyx is light DOM throughout). Load it before or alongside the script. Skipping it leaves the page with unstyled native elements: functional, but not what you want to ship.

Your first component

Paste this into an empty .html file, next to the local build's <link>/<script> tags from the notice above (the CDN path doesn't work yet, see that notice):

<oblyx-button variant="primary">Save</oblyx-button>

oblyxButton(variant = OblyxButtonVariant.PRIMARY) { +"Save" }

Server-side: Kotlin and Ktor

Building a Ktor + HTMX server instead of a static page? See Kotlin and Ktor installation for the oblyx-ktor Gradle dependency and the type-safe HTML DSL generated from the same component manifest as this page's Kotlin tab.

Theming

Every color, spacing and shape value Oblyx uses is a CSS custom property with a light and dark default. See Theming and color scheme to override them or to wire up a light/dark toggle.