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.

Published on npm, with every documented component included. The CDN link and install command below both work.

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 CDN <link>/<script> tags above:

<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.