@sometic/elements

Vanilla custom elements (sometic-*) powered by Sometic DOM engines.

@sometic/elements registers light-DOM-first Web Components that wrap the same controllers and resolvers used by framework adapters. Tags such as sometic-button, sometic-input, sometic-dialog, and sometic-form give HTML-first apps (or progressive enhancement stacks) a component surface without pulling React or Vue.

These elements exist so Vanilla, HTMX-adjacent, and multi-framework teams can share one behavior model. Engines live in @sometic/dom; elements are a thin custom-element shell that maps attributes, slots, and sometic-* events onto those engines. Optional Shadow DOM is available via a shadow attribute where supported, but Light DOM remains the default for form association and consumer styling.

Standout features include grouped registration helpers (registerButtonElements, registerInputElements, registerOverlayElements, …), typed custom events (SometicValueChangeDetail, SometicFormSubmitDetail, SometicOpenChangeDetail), and subpath imports (@sometic/elements/button, @sometic/elements/input, @sometic/elements/form, @sometic/elements/overlay) so you only register the families you need. Side-effect imports define the sometic-* tags once per registry.

Ecosystem placement: elements depend on @sometic/dom, @sometic/forms, @sometic/validation, and @sometic/auth for status/form wiring, while foundation utilities come from @sometic/core. Start with the introduction and the Vanilla guide.

Install

pnpm add @sometic/elements

npm install @sometic/elements

yarn add @sometic/elements

Usage

Register button elements, then use them in HTML:

import { registerButtonElements } from "@sometic/elements/button";

registerButtonElements();

<sometic-button type="button" size="md" variant="primary"> Save </sometic-button>

<sometic-async-button> Run action </sometic-async-button>

Register overlays and listen for open changes:

import { registerOverlayElements, type SometicOpenChangeDetail } from "@sometic/elements/overlay";

registerOverlayElements();

const dialog = document.querySelector("sometic-dialog");
dialog?.addEventListener("open-change", (event) => {
    const detail = (event as CustomEvent<SometicOpenChangeDetail>).detail;
    console.log("open", detail.open);
});

CDN

Docs: https://sometic.dev/frameworks/vanilla.

Simple script

<script src="https://cdn.jsdelivr.net/npm/@sometic/[email protected]/dist/cdn/sometic-elements.iife.js"></script>

<sometic-button type="button">Save</sometic-button>

Module script

<script
    type="module"
    src="https://cdn.jsdelivr.net/npm/@sometic/[email protected]/dist/cdn/sometic-elements.esm.js"
></script>

<sometic-button type="button">Save</sometic-button>

Peers / when not to use

No framework peers. Dependencies include @sometic/dom, @sometic/forms, @sometic/validation, @sometic/auth, and date packages for date inputs.

Prefer framework adapters (@sometic/react, @sometic/vue) when you want JSX/SFC components with framework lifecycle. Prefer raw @sometic/dom when you need controllers without custom elements. Do not import element side-effect barrels on the server without a custom-elements-safe guard.

Docs

• Introduction
• Vanilla / Web Components
• DOM engines
• Components

License

MIT