Thyme UI

A lightweight UI component library built with native Web Components (Custom Elements + Shadow DOM), zero third-party dependencies.

https://metadream.github.io/thyme-ui — live demo

Installation

CDN (recommended)

<script src="https://unpkg.com/@metadream/thyme-ui"></script>

This single script registers all components and exposes the Thyme global API.

Build from source

npm install        # installs terser
npm run build      # outputs docs/thyme.min.js

---

Components

All components follow these conventions:

• Native-like .value, .name, .checked, .type properties for uniform form handling
• Date format: yyyy-mm-dd throughout
• Attributes are reactive — changes after render are reflected automatically

---

<th-button>

A button with four visual variants, loading state, ripple effect, and optional link mode.

Attributes

Attribute	Type	Default	Description
variant	string	"filled"	One of: filled, tonal, outlined, ghost
size	string	—	"small", "large", or omit for medium
disabled	boolean	—	Disables the button
loading	boolean	—	Shows spinner, disables interaction
href	string	—	When set, renders an <a> instead of <button>
target	string	—	Link target (only when href is set)
rel	string	—	Link rel (only when href is set)
download	string	—	Link download (only when href is set)
type	string	—	Button type attribute ("submit", "reset", "button")
name	string	—	Button name
value	string	—	Button value
form	string	—	Associated form ID
autofocus	boolean	—	Auto-focus on mount

Slots

Slot	Description
default	Button label text
"icon"	Icon element. When only icon is present (no text), the button renders as a square icon-only button

CSS Shadow Parts

Part	Element
button	The inner <button> or <a>
content	<span> wrapping the slots
loader	Loading spinner <span>

Examples

<th-button>Filled</th-button>
<th-button variant="tonal">Tonal</th-button>
<th-button variant="outlined">Outlined</th-button>
<th-button variant="ghost">Ghost</th-button>

<th-button size="small">Small</th-button>
<th-button size="large">Large</th-button>

<th-button loading>Saving...</th-button>
<th-button disabled>Disabled</th-button>

<!-- Link mode -->
<th-button href="https://example.com" target="_blank">Link</th-button>

<!-- Icon-only -->
<th-button><svg slot="icon">...</svg></th-button>

---

<th-field>

A form field with label, input/textarea/date picker, built-in validation, and error display.

Attributes

Attribute	Type	Default	Description
label	string	—	Field label text
type	string	"text"	One of: text, email, number, date, textarea
value	string	—	Current input value
name	string	—	Field name for form serialization
placeholder	string	—	Placeholder text
required	boolean	—	Marks as required (shows * in label)
disabled	boolean	—	Disables the input
readonly	boolean	—	Makes input read-only
minlength	number	—	Minimum text length
maxlength	number	—	Maximum text length
rows	number	3	Textarea row count (only when type="textarea")
min	string	—	Minimum value (for number/date types)
max	string	—	Maximum value (for number/date types)
pattern	string	—	Regex pattern for validation
autocomplete	string	—	Autocomplete hint
autofocus	boolean	—	Auto-focus on mount
error	string	—	Sets an error message (overrides validation). Remove attr to clear

Note: When type="date", the built-in input is type="text" with maxlength="10" (for yyyy-mm-dd format) and a custom calendar popup. Validation checks the date format, real date existence, and optional min/max constraints.

Properties

Property	Type	Get/Set	Description
.value	string	get/set	Current input value
.name	string	get	Field name attribute
.disabled	boolean	get/set	Whether the field is disabled
.readonly	boolean	get/set	Whether the field is read-only
.required	boolean	get/set	Whether the field is required

Methods

Method	Returns	Description
.checkValidity()	boolean	Returns whether the input passes validation
.reportValidity()	boolean	Checks validity and shows error message if invalid
.setCustomValidity(msg)	void	Sets a custom validation error. Pass empty string to clear
.focus()	void	Focuses the inner input/textarea

Events (native, delegated from inner <input>/<textarea>)

Event	Description
input	Fires on every value change (bubbles)
change	Fires when value is committed (bubbles)
invalid	Fires when validation fails

Slots

Slot	Description
default	Replaces the built-in <input>/<textarea> with a custom element (the custom element must have .value and support the expected attributes). When type="textarea", light DOM text content is consumed as the initial value
"label"	Replaces the label text

CSS Shadow Parts

Part	Element
field	Outer container
label	<label> element
input	The <input> or <textarea>
error	Error tooltip <span>
date-btn	Calendar toggle button (only when type="date")
calendar	Date picker popup (only when type="date")

Examples

<!-- Text input -->
<th-field label="Name" name="username" placeholder="Enter your name"></th-field>

<!-- Email with validation -->
<th-field label="Email" type="email" name="email" required></th-field>

<!-- Number -->
<th-field label="Age" type="number" name="age" min="0" max="150"></th-field>

<!-- Date picker -->
<th-field label="Date" type="date" name="date"></th-field>

<!-- Textarea with slot content consumed as initial value -->
<th-field label="Bio" type="textarea" name="bio" rows="5">
  <p>Existing content</p>
</th-field>

<!-- Pre-filled value -->
<th-field label="City" value="Shanghai"></th-field>

<!-- With error -->
<th-field label="Password" type="password" error="Too short"></th-field>

<!-- Disabled -->
<th-field label="Readonly" value="Immutable" disabled></th-field>

<!-- Using slot for label -->
<th-field name="email">
    <span slot="label">Email Address</span>
</th-field>

---

<th-check>

Checkbox or radio button with custom styling.

Attributes

Attribute	Type	Default	Description
type	string	"checkbox"	Either "checkbox" or "radio"
checked	boolean	—	Whether the element is checked
disabled	boolean	—	Disables interaction
name	string	—	Group name (radio buttons with same name auto-uncheck each other)
value	string	—	Value submitted with form

Properties

Property	Type	Get/Set	Description
.checked	boolean	get/set	Checked state
.disabled	boolean	get	Disabled state
.type	string	get	"checkbox" or "radio"
.name	string	get	Name attribute
.value	string	get	Value attribute

Events

Event	Detail	Description
change	{ checked: boolean, value: string }	Fires on toggle (bubbles)

Slots

Slot	Description
default	Label text displayed next to the indicator

Examples

<th-check checked>Remember me</th-check>
<th-check type="radio" name="gender" value="male">Male</th-check>
<th-check type="radio" name="gender" value="female">Female</th-check>
<th-check disabled>Disabled</th-check>

<!-- Programmatic -->
<script>
    const cb = document.querySelector('th-check');
    cb.checked = true;
    cb.addEventListener('change', (e) => console.log(e.detail));
</script>

---

<th-switch>

A toggle switch.

Attributes

Attribute	Type	Description
checked	boolean	Toggle state
disabled	boolean	Disables interaction
value	string	Value returned when checked

Properties

Property	Type	Get/Set	Description
.checked	boolean	get/set	Toggle state
.disabled	boolean	get	Disabled state
.value	string|number	get	Returns attribute value or 1 when checked, undefined when unchecked

Events

Event	Detail	Description
change	{ checked: boolean }	Fires on toggle (bubbles)

Examples

<th-switch checked>Notifications</th-switch>
<th-switch disabled>Unavailable</th-switch>

---

<th-select>

A custom select dropdown built from <option> children.

Attributes

Attribute	Type	Description
label	string	Label text shown to the left
value	string	Currently selected value
placeholder	string	Placeholder text when no option is selected
disabled	boolean	Disables the select
name	string	Field name for form serialization
required	boolean	Marks as required

Properties

Property	Type	Get/Set	Description
.value	string	get/set	Currently selected value
.disabled	boolean	get/set	Disabled state
.name	string	get	Name attribute
.checkValidity()	boolean	—	Returns whether validation passes
.reportValidity()	boolean	—	Checks validity and shows error if invalid
.focus()	void	—	Focuses the trigger element

Events

Event	Detail	Description
change	{ value: string, text: string }	Fires when an option is selected (bubbles)

Children

Uses standard <option> elements:

<option value="cn">China</option>
<option value="us" selected>United States</option>

The selected attribute on an <option> sets the initial value.

CSS Shadow Parts

Part	Element
select	Outer container
label	<label> element
trigger	Clickable trigger bar
value	Value display <span>
panel	Dropdown panel
error	Error message <span>

Keyboard navigation

Key	Action
Enter / Space	Open dropdown, or confirm highlighted option
Escape	Close dropdown
ArrowDown	Highlight next option (opens if closed)
ArrowUp	Highlight previous option (opens if closed)

Examples

<th-select label="Country" name="country">
    <option value="cn">China</option>
    <option value="us" selected>United States</option>
    <option value="jp">Japan</option>
</th-select>

<!-- With placeholder -->
<th-select label="City" placeholder="Select a city...">
    <option value="shanghai">Shanghai</option>
    <option value="beijing">Beijing</option>
</th-select>

<!-- Programmatic -->
<script>
    const sel = document.querySelector('th-select');
    sel.value = 'jp';
    console.log(sel.value); // 'jp'
    sel.addEventListener('change', (e) => console.log(e.detail));
</script>

---

<th-dialog>

A modal dialog with overlay, title, body, and footer slot.

Attributes

Attribute	Type	Default	Description
open	boolean	—	Whether the dialog is visible
title	string	—	Dialog title text
closable	boolean	true	Whether Escape key can close the dialog
width	number	—	Fixed dialog width in pixels (overrides CSS default)

Methods

Method	Description
.open()	Opens the dialog (sets open attribute)
.close()	Closes the dialog with animation (removes open attribute)

Slots

Slot	Description
default	Dialog body content
"footer"	Footer buttons. When empty, the footer is hidden. Buttons are styled automatically

CSS Shadow Parts

Part	Element
overlay	Fixed full-screen overlay
dialog	Dialog panel
title	Title bar
body	Body content area
footer	Footer area

Behavior

• Body scroll is prevented while open (wheel + touchmove)
• Escape key closes the dialog (unless closable="false")
• Clicking the overlay does NOT close the dialog

Examples

<th-dialog id="myDialog" title="Confirm">
    <p>Are you sure?</p>
    <button slot="footer">OK</button>
    <button slot="footer">Cancel</button>
</th-dialog>

<script>
    document.querySelector('#myDialog').open();
</script>

---

<th-toast>

A fixed-position toast notification. Auto-removes after a duration. Multiple toasts stack vertically.

Attributes

Attribute	Type	Default	Description
type	string	"info"	One of: info, warn, error, success
duration	number	3	Display duration in seconds

Methods

Method	Description
.close()	Closes the toast immediately and dispatches a close event

Events

Event	Detail	Description
close	—	Dispatched when the toast is closed (bubbles)

Slots

Slot	Description
default	Toast message text

CSS Shadow Parts

Part	Element
toast	The toast <div>

Styling

Type	Background	Text
info	Dark gray (80%)	White
warn	Yellow (80%)	Dark
error	Red (80%)	White
success	Green (80%)	White

Examples

<th-toast type="success">Saved successfully!</th-toast>
<th-toast type="error" duration="5">Connection failed</th-toast>

---

Global API (self.Thyme)

After the script loads, Thyme is available globally.

Dialogs

Thyme.alert('Hello World');
Thyme.alert('File deleted', 'Warning');

// Returns Promise<boolean>
const ok = await Thyme.confirm('Delete this item?');
if (ok) { /* proceed */ }

Toast notifications

Thyme.info('Loading...');
Thyme.success('Done!', 2);           // 2 seconds
Thyme.warn('Low disk space', 5);     // 5 seconds
Thyme.error('Something broke', 10);  // 10 seconds

Locale / i18n

Thyme.locale = 'zh';  // switch to Chinese
Thyme.locale = 'en';  // switch to English

Form utilities

// Serialize a form scope to an object.
// Returns null if ANY field fails checkValidity() — the first
// invalid field receives focus and shows its error message.
const data = Thyme.form.getJsonObject('#my-form');
// or pass an element:
const data = Thyme.form.getJsonObject(document.querySelector('#my-form'));

// Serialize multiple form scopes to an array.
// Returns null if ANY scope's validation fails.
const all = Thyme.form.getJsonArray('.form-scope');
// or pass a NodeList:
const all = Thyme.form.getJsonArray(document.querySelectorAll('.form-scope'));

// Populate a form from an object
Thyme.form.setJsonObject('#my-form', { username: 'admin', age: 25 });

// Typical submit guard:
const data = Thyme.form.getJsonObject('#my-form');
if (data === null) return;  // validation failed, already focused
await fetch('/api/submit', { method: 'POST', body: JSON.stringify(data) });

Rules for serialization (getJsonObject / getJsonArray):

• Only elements with a name attribute are included
• Unchecked checkboxes / radio buttons / switches are skipped
• Checkboxes with the same name or <select multiple> are collected into an array
• contentEditable elements use trimmed innerHTML
• User-input elements (native <input>/<textarea>, <th-field>) have their value trimmed and written back to the element
• Selection elements (<select>, <th-select>, <th-check>, <th-switch>, radio buttons) are stored as-is
• On any checkValidity() failure, getJsonObject returns null immediately — the first invalid field is focused and shows its error

setJsonObject populates elements by matching [name] attributes. Handles all the same element types including <select multiple>, checkbox arrays, radio groups, and contentEditable.

HTTP client

Thyme.http wraps fetch() with JSON handling, response type detection, and error reporting.

Methods

const data   = await Thyme.http.get(url, opts?)
const data   = await Thyme.http.post(url, data?, opts?)
const data   = await Thyme.http.put(url, data?, opts?)
const data   = await Thyme.http.patch(url, data?, opts?)
const data   = await Thyme.http.delete(url, opts?)

Parameters

Param	Type	Description
url	string	Request URL
data	any	Request body. Plain objects/arrays are JSON-stringified automatically. FormData, Blob, ArrayBuffer sent as-is. Omit for GET/DELETE
opts	object	Additional fetch options merged into the request (signal, credentials, custom headers, etc.)

Examples

// GET
const users = await Thyme.http.get('/api/users');

// POST with JSON body
const user = await Thyme.http.post('/api/users', { name: 'Alice' });

// PUT
await Thyme.http.put('/api/users/1', { name: 'Bob' });

// PATCH
await Thyme.http.patch('/api/users/1', { name: 'Bob' });

// DELETE
await Thyme.http.delete('/api/users/1');

Custom fetch options

Pass native fetch() options through the third argument:

// Abort request
const controller = new AbortController();
Thyme.http.get('/api/search', { signal: controller.signal });
controller.abort();

// Custom headers (merged with defaults)
Thyme.http.post('/api/data', { foo: 1 }, {
    headers: { Authorization: 'Bearer xxx' }
});

// FormData (not JSON-stringified)
const form = new FormData();
form.append('file', file);
await Thyme.http.post('/api/upload', form);

Response types

The response body is parsed automatically based on Content-Type:

Content-Type	Parsed as
text/*	response.text()
application/json	response.json()
Everything else	response.blob()

Non-OK status codes (4xx/5xx) throw an Error with the parsed server message.

Error handling

try {
    await Thyme.http.get('/api/data');
} catch (e) {
    console.error(e.message); // server error message or "Unknown error"
}

Errors are also passed to Thyme.error() automatically.

Utility functions

Thyme.utils.delay(1000);                // Promise that resolves after 1s

Thyme.utils.nanoId();                   // Random 24-char ID (0-9a-zA-Z)
Thyme.utils.nanoId(8);                  // Random 8-char ID

Thyme.utils.formatDate(new Date(), 'yyyy-MM-dd');              // "2026-05-15"
Thyme.utils.formatDate(new Date(), 'yyyy-MM-dd hh:mm:ss');     // "2026-05-15 14:30:00"
Thyme.utils.formatDate(new Date(), 'MM/dd/yyyy', true);        // "05/15/2026" in UTC

Thyme.utils.formatDecimal(3.14159, 2);  // 3.14
Thyme.utils.formatMoney(1234567.89);    // "1,234,567.89"
Thyme.utils.formatBytes(1048576);       // "1 MiB"

Thyme.utils.parseDuration('01:30:00');  // 5400 (seconds)
Thyme.utils.formatSeconds(3661);        // "1h 1m 1s"

Thyme.utils.base64Encode('hello');      // "aGVsbG8="

---

Theming

Set these CSS custom properties on any ancestor element — they inherit through Shadow DOM:

:root {
    --th-primary: #3730a3;    /* Primary color, default: indigo-800 */
    --th-radius: 8px;         /* Border radius, default: 8px */
    --th-font-size: 14px;     /* Base font size */
    --th-line-height: 1.5;    /* Base line height */
}

All derived colors (hover, ripple, border, focus ring) are computed automatically from --th-primary via color-mix() — no additional variables needed.

Styling via ::part()

Each component exposes CSS shadow parts for granular styling:

th-button::part(button) {
    font-weight: 700;
}
th-field::part(input) {
    font-family: monospace;
}
th-dialog::part(dialog) {
    max-width: 500px;
}

---

Browser Support

Chrome 111+ / Firefox 128+ / Safari 16.2+ / Edge 111+.

Requires @property CSS at-rule and color-mix(). IE is not supported.

---

Architecture (for contributors)

See AGENTS.md for build process, file conventions, and internal architecture details.