Components

Reach for a th-* element before you hand-roll a button, panel or menu. They are Lit web components from @teamhud/ui-core, styled entirely from --th-* tokens, so they follow the person’s density, accent and theme.

Use a component

Register the element with a side-effect import, then use the tag. Import one element, or every element at once in a window bootstrap.

import '@teamhud/ui-core/components/th-button.js';   // one element (the usual form)
import '@teamhud/ui-core/all';                       // every element (window / renderer bootstraps only)

<th-button variant="primary" size="sm">Save</th-button>

Types and helpers (ThTab, ThContextMenuItem, ThToastVariant) come from the @teamhud/ui-core barrel. Layout elements live one folder down: components/layout/th-stack.js, components/state/th-state-block.js.

Custom widgets run in a sandboxed frame and use a smaller, self-contained set; see Elements for custom widgets.

Controls

Element	Use it for	Key attributes	Events
th-button	Any button. Slot is the label.	variant (primary secondary ghost danger warning link), size (xs to lg), disabled, block, hold-ms (press and hold to confirm)	native click; th-hold-start, th-hold-complete, th-hold-cancel
th-icon-button	Icon-only button.	icon (catalog name), label, size, tone (success danger warning), active, pressed, tooltip, disabled; slot for an inline <svg>	native click
th-split-button	A main action plus a caret menu.	icon, tooltip, caret-tooltip, expanded, tone, size	th-split-main, th-split-caret (detail.anchor)
th-input	One-line text.	type, value, label, placeholder, error, size, disabled, required; slots leading, trailing	input, change
th-textarea	Multi-line text.	value, label, rows, maxlength, resize, error, size	input, change (detail.value)
th-select	Pick one option.	options (array of { value, label }), value, label, placeholder, error, size	change
th-checkbox	Tick box. Slot is the label.	checked, indeterminate, disabled, label	change (detail.checked)
th-toggle	On/off switch.	checked, disabled, size, label	change
th-slider	A number in a range.	min, max, step, value, label, unit, hide-value	input while dragging, change on commit (detail.value)
th-color-picker	A colour, with optional opacity.	value (hex), alpha	change (detail.value)

<th-slider label="Opacity" min="0" max="100" step="5" value="80" unit="%"></th-slider>
<script type="module">
  document.querySelector('th-slider').addEventListener('change', (e) => console.log(e.detail.value));
</script>

Display and feedback

Element	Use it for	Key attributes	Events
th-badge	Small status or count label.	variant (default success warning danger info count, plus slack gmail gdrive), size (sm md)	none
th-chip	A tag or filter; optionally removable.	variant (default accent success warning danger info), selected, removable	th-remove
th-tabs	Switch between views.	tabs (array of { key, label, icon?, count?, disabled? }), activeKey, variant (underline pill segmented), size	th-change (detail.key)
th-toast / th-toast-stack	Short notices.	variant (default success error warning info), message, dismissible; stack takes toasts	th-close; stack: th-dismiss
th-tooltip	Hover text around a slotted element.	text, position, delay	none
th-spinner	Loading.	size, label	none
th-icon	A catalog icon.	name, size (xs to xl), rotate	none
th-empty-state	Nothing here, loading, error, info.	variant (empty loading error info), message, subtext, icon; slot action	none
th-state-block	A compact version of the same.	variant, message, subtext, icon	none
th-section-header	A collapsible list heading with a count.	icon, label, count, collapsed, label-only; slot actions	toggle

Containers and layout

Element	Use it for	Key attributes and slots	Events
th-hub-panel	The overlay pop-out panel. Do not write your own placement.	side (right left top bottom), dx, dy, revealed, resizable; slots header, default, footer	th-rect-change, th-panel-entrance-end, th-panel-exit-end, th-resize, th-resize-end
th-hub-panel-header	Standard panel header.	slots title, tabs, actions	none
th-panel	A simple surface with a header.	width, maxHeight; slots header, default	none
th-card	A grouped block.	variant (default elevated panel-item), padding, interactive; slots header, default, footer	none
th-modal	A dialog.	open, size (sm md lg full), closeOnBackdrop, showClose; slots header, default, footer	close
th-context-menu	A right-click or caret menu.	items (array of { key, label, icon?, section?, divider? }), top, left, minWidth	th-select (detail.key), th-close
th-scroll-area	Themed scrolling.	axis, max-height	none
th-stack, th-grid	Spacing and columns.	gap; divider on stack; columns on grid	none
th-flex-split, th-three-panel	Two or three columns.	left-width, right-width (main-width), gap, stacked; named slots	none
th-window-shell	A full app window frame.	slots header, sidebar, default	none

<th-card variant="elevated" padding="md">
  <span slot="header">Status</span>
  <th-chip variant="success">Online</th-chip>
</th-card>

Preferences building blocks

A preferences pane is th-prefs-pane containing th-setting-group elements, each holding th-setting-rows. They give you the standard heading, search highlight, “Advanced” fold and row layout for free.

<th-prefs-pane heading="My plugin" subtitle="Settings for my plugin.">
  <th-setting-group label="General">
    <th-setting-row label="Enabled" description="Turn the feature on or off.">
      <th-toggle checked></th-toggle>
    </th-setting-row>
  </th-setting-group>
</th-prefs-pane>

th-prefs-pane slots: actions (primary action, top right), banner, default. th-setting-group slots: default, advanced, footer, header-end. th-option-card is a selectable card with slots cover, badges, tags, meta, control, and the selected, unavailable and reason attributes.

Note

Other elements exist for specific features: th-rich-compose and th-emoji-picker (messaging), th-team-invite, th-link-popover, th-widget-settings (schema-driven options), th-theme-canvas and the override editors (th-hub-override, th-panel-override) used by the theme editor.

Elements for custom widgets

A custom widget loads a self-contained set that needs no library, plus the matching .th-* classes. Add <link rel="stylesheet" href="teamhud-widget://_shared/widget.css"> for the classes.

Element	Use it for	Attributes
th-section	A content group with a caption.	label
th-kv-row	A label and value row.	label
th-progress	A labelled progress bar.	name, value, sub, warn-at, error-at
th-chip	A pill.	variant (default warn error muted)
th-btn	A button.	variant (default primary), disabled
th-widget-footer	A footer strip.	none

Caution

th-chip exists twice with different variant values: the widget set uses warn and error, the full library uses warning and danger.

Token groups

Components read tokens and never hard-coded values, so override tokens, not component internals. The groups are:

• Surfaces, text, borders (--th-bg-*, --th-text-*, --th-border-*)
• Accent ramp and semantic colours (--th-accent-*, --th-success-*, --th-warning-*, --th-danger-*)
• Spacing, radii, type (--th-space-*, --th-radius-*, --th-text-*, --th-font-*), all scaled by the density unit --th-u
• Motion and layering (--th-duration-*, --th-ease-*, --th-z-*, --th-shadow-*)
• Overlay panel surface (--th-overlay-panel-*, --th-panel-w-*) and panel parts, scrollbar and icon sizes

The full list, the rules and the contrast requirements are in Theming & styling.

Where next

• Create a theme
• Build your first custom widget
• Widget permissions