harmonia

name	harmonia
description	How to build UIs with the Harmonia Alpine.js component library (@codbex/harmonia). Use when adding, wiring, or styling Harmonia UI components (x-h-* directives such as buttons, dialogs, selects, tables, date pickers) in a project that depends on @codbex/harmonia.

Harmonia

Harmonia is a UI component library for Alpine.js, built with Tailwind CSS. Components are Alpine directives: you add x-h-* attributes to plain HTML elements and the library upgrades them. There is no JSX and no component-tag syntax.

Full documentation: https://www.codbex.com/harmonia/

How to use this skill

Find the component in the index below and open its file under references/. Each reference lists the directive set, its attributes, whether it binds with x-model, and working examples you can adapt. Load only the reference(s) you need.

Setup

Harmonia requires Alpine.js as a peer dependency and ships a CSS file that must be linked.

Script tag (auto-registers on alpine:init)

<script src="/path/to/node_modules/@codbex/harmonia/dist/harmonia.min.js"></script>
<link href="/path/to/node_modules/@codbex/harmonia/dist/harmonia.css" rel="stylesheet" />
<script defer src="/path/to/node_modules/alpinejs/dist/cdn.min.js"></script>

ES module (register manually)

import Alpine from 'alpinejs';
import registerComponents from '@codbex/harmonia';

registerComponents(Alpine.plugin); // register every component
Alpine.start();

Import the CSS (@codbex/harmonia/dist/harmonia.css) too. For selective registration, import named exports (import { Button, Card } from '@codbex/harmonia') and call Alpine.plugin(Button) per component.

Conventions that apply to every component

• Directive prefix. Alpine directives registered as h-<name> are written as x-h-<name> in HTML (for example x-h-button, x-h-date-picker).
• Values are Alpine expressions. A string literal must be quoted inside the attribute value: x-h-accordion-trigger="'Section title'", not x-h-accordion-trigger="Section title". A bare word is read as a variable reference.
• Compound components nest. Many components are a set of directives (root plus children). They must be nested as the reference example shows; the library throws a descriptive error at runtime if a required ancestor is missing.
• Modifiers are dot suffixes. For example x-h-accordion.single, x-h-accordion-item.default.
• Styling is attribute-driven. Common attributes are data-size (for example sm / md), data-variant (for example primary / negative), and data-align for popovers/menus. See each reference for the exact values.
• Utility classes are a curated subset, NOT all of Tailwind. Only the classes compiled into harmonia.css exist; an arbitrary Tailwind class that is not shipped (for example h-80, gap-20, bg-red-450) silently does nothing. Before using any utility class, confirm it is in the Utility classes reference, and for a one-off value with no matching class use an inline style.
• Form controls use x-model. Inputs, selects, checkboxes, radios, ranges, switches, and the date/time pickers bind their value with Alpine x-model.
• Light and dark modes are handled automatically.
• Accessibility. Components set sensible ARIA roles and a default aria-label only when the author has not set one; provide your own labels where the content is not self-describing.

Component index

Components

Name	Description	Reference
Accordion	Organizes related content into expandable and collapsible sections, allowing users to reveal or hide information as needed while keeping the interface clean and compact.	accordion
Alert	Communicates important information to the user about a situation or task that requires attention.	alert
Avatar	Represents a person, entity, or object using an image, icon, or text, such as a user photo, initials, or symbolic graphic.	avatar
Badge	Displays a short label used to convey the semantic status of an object.	badge
Breadcrumb	Displays the current page's location within a navigational hierarchy, helping users understand where they are and navigate back to parent pages.	breadcrumb
Button	Buttons can trigger an action or navigate the user to another location.	button
Button Group	Groups related buttons into a single container to present them as a unified set of actions.	button-group
Calendar	A full multi-view event calendar with month, week, day, and year views.	calendar
Card	A flexible container that organizes content into distinct sections, typically including a header, main content area, and footer.	card
Checkbox	Allows users to select or deselect an option, representing a binary choice (true/false).	checkbox
Chip	A compact, interactive element used to represent an applied filter, a selected item, or a categorization.	chip
Date Picker	Allows users to enter a date either by typing it directly or by selecting it from a calendar popover.	date-picker
Date Time Picker	Lets users pick a date and a time together.	datetime-picker
Dialog	A modal container that appears in response to a user action, temporarily interrupting the current workflow to request information or confirmation.	dialog
Expansion Panel	The Expansion Panel is a container component that manages multiple collapsible panels within a layout.	expansion-panel
Fieldset	A container that groups related form elements, including labels, controls, and helper text, to create accessible and organized input sections.	fieldset
File Upload	Lets users choose one or more files for upload.	file-upload
Icon	Renders an SVG graphic, either from a link or a set of built-in icons, that can represent an action, status, or decorative element.	icon
Info Page	Provides a structured layout to display instructional content, messages, or status information, such as empty states or error notifications.	info-page
Inline Calendar	A compact calendar for selecting a single date or a date range within a monthly context.	inline-calendar
Input	Provides a single-line field for users to enter text or color values.	input
Input Group	Combines an input or textarea field with related elements, such as buttons, icons, or labels, to create a cohesive and interactive form control.	input-group
Input Number	Allows users to enter numeric values with built-in validation and step controls.	input-number
Label	Provides an accessible caption for a user interface element, most commonly paired with input controls.	label
List	A container that displays a collection of related items in a structured format.	list
Listbox	A single-selection list component with support for grouped options, functionally similar to an HTML <select> element.	listbox
Menu	A structured list of options, optionally including headers, used to create navigational menus, context menus, or dropdowns.	menu
Navigation Menu	A horizontal navigation bar where items are either direct links or triggers that open a dropdown Menu.	navigation-menu
Notifications	The Notification component is used to present important system feedback, status updates, or contextual information to the user.	notifications
Pagination	Divides content into discrete pages, allowing users to navigate large datasets or collections more easily.	pagination
Popover	Displays supplementary information or content in a compact overlay without navigating away from the current page.	popover
Progress	Visually represents the completion status of an ongoing operation, providing users with feedback on progress and expected duration.	progress
Radio	A single-choice input that allows users to select one option from a set.	radio
Range	Allows users to select a value, or a range of values, by dragging a handle along a track.	range
Rating	Lets users view and set a star rating.	rating
Select	Allows users to choose one or more items from a predefined list of options.	select
Separator	A simple visual divider used to separate content or sections within an interface.	separator
Sheet	The sheet component is a side panel that overlays the window content and is shown on one side of the screen.	sheet
Sidebar	A vertical navigation panel used to present top-level application links or sections.	sidebar
Skeleton	A placeholder component used to indicate that content is loading.	skeleton
Slot Picker	An inline calendar that shows three consecutive days, each with a grid of selectable time slots.	slot-picker
Spinner	A visual indicator that signals an ongoing operation or process.	spinner
Step Indicator	Communicates progress through a sequence of steps, showing which steps are completed, which one is active, and which are still ahead.	step-indicator
Switch	Allows users to toggle a binary state, such as true/false or on/off.	switch
Table	Organizes data into rows and columns, with each row representing a single item and each column representing a specific attribute.	table
Tabs	Organizes content into multiple sections, displaying only one section at a time while keeping others easily accessible through a tabbed navigation interface.	tabs
Tag	A compact element used to display small pieces of information, labels, or metadata.	tag
Text	Applies consistent typography styles to headings, paragraphs, single lines, and code blocks, ensuring a cohesive visual hierarchy and readability across the interface.	text
Textarea	Provides a multi-line input field for users to enter longer text.	textarea
Tile	A container that presents content, previews, or shortcuts in a compact, visually distinct format.	tile
Time Picker	Allows users to select a specific time, providing a controlled and consistent input method for hours, minutes and seconds.	time-picker
Toolbar	A container that groups actions (like buttons, inputs, or popovers) relevant to the current view.	toolbar
Tooltip	A small pop-up that provides additional information or context about an interface element, displayed on hover.	tooltip
Tree	Displays hierarchical data in a structured, expandable format, allowing users to explore nested items efficiently.	tree

Charts

Name	Description	Reference
Bar Chart	x-h-chart-bar draws a bar chart from a single reactive configuration object.	bar
Doughnut Chart	x-h-chart-doughnut draws a doughnut chart (a pie with a hole in the middle) from a single reactive configuration object.	doughnut
Line Chart	x-h-chart-line draws a line chart from a single reactive configuration object.	line
Pie Chart	x-h-chart-pie draws a pie chart from a single reactive configuration object.	pie
Scatter Chart	x-h-chart-scatter draws a scatter chart from a single reactive configuration object: the same plot as a line chart, but with only the points and no connecting lines.	scatter

Layouts

Name	Description	Reference
Split	The split component provides a flexible layout for dividing content into resizable panels.	split

Utilities

Name	Description	Reference
Breakpoint Listener	Creates a listener that triggers actions when the viewport reaches specified breakpoint.	breakpoint-listener
Date Format	A behavior-only directive that renders a date value as a locale-aware date string into the element's text content.	date-format
Focus	A behavior-only directive that programmatically sets focus on an element based on a specified condition.	focus
Include	The include directive makes it easy to fetch and insert an external HTML fragment inside an element.	include
Template	The template directive makes it easy to insert and initialize an Alpine.js snippet inside a referenced <template> element.	template
Theme	Utility functions for retrieving and updating the color scheme.	theme

Plugins

Name	Description	Reference
i18next	An optional plugin that binds the i18next internationalization library to Alpine and Harmonia.	i18next
Lucide	An optional plugin that keeps Lucide icons in sync with the Alpine/Harmonia lifecycle.	lucide

Utility classes

Name	Description	Reference
Utility classes	The complete allowlist of Tailwind utility classes available in harmonia.css (not the full Tailwind set).	utility-classes