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

<!-- AUTO-GENERATED by scripts/generate-agent-docs.cjs from docs/. Edit that script (or the source docs), then run `npm run build`. -->

# Harmonia

Harmonia is a UI component library for [Alpine.js](https://alpinejs.dev/), 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`)

```html
<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)

```js
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](references/utility-classes.md) 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](references/accordion.md) |
| Alert | Communicates important information to the user about a situation or task that requires attention. | [alert](references/alert.md) |
| Avatar | Represents a person, entity, or object using an image, icon, or text, such as a user photo, initials, or symbolic graphic. | [avatar](references/avatar.md) |
| Backdrop | A full-screen overlay that dims the page and animates its content in and out. | [backdrop](references/backdrop.md) |
| Badge | Displays a short label used to convey the semantic status of an object. | [badge](references/badge.md) |
| Bottom Navigation | A bar of top-level destinations along the bottom of the screen, each an icon over a short label, with the current one highlighted. | [bottom-nav](references/bottom-nav.md) |
| Breadcrumb | Displays the current page's location within a navigational hierarchy, helping users understand where they are and navigate back to parent pages. | [breadcrumb](references/breadcrumb.md) |
| Bubble | A chat message bubble with left and right alignment, semantic color variants, and optional previews for image, audio, file and link attachments. | [bubble](references/bubble.md) |
| Button | Buttons can trigger an action or navigate the user to another location. | [button](references/button.md) |
| Button Group | Groups related buttons into a single container to present them as a unified set of actions. | [button-group](references/button-group.md) |
| Calendar | A full multi-view event calendar with month, week, day, and year views. | [calendar](references/calendar.md) |
| Card | A flexible container that organizes content into distinct sections, typically including a header, main content area, and footer. | [card](references/card.md) |
| Carousel | A slideshow that cycles through a set of slides one at a time, with previous/next controls, indicator dots, keyboard navigation, wraparound looping, and optional autoplay. | [carousel](references/carousel.md) |
| Checkbox | Allows users to select or deselect an option, representing a binary choice (true/false). | [checkbox](references/checkbox.md) |
| Chip | A compact, interactive element used to represent an applied filter, a selected item, or a categorization. | [chip](references/chip.md) |
| Date Picker | Allows users to enter a date either by typing it directly or by selecting it from a calendar popover. | [date-picker](references/date-picker.md) |
| Date Time Picker | Lets users pick a date and a time together. | [datetime-picker](references/datetime-picker.md) |
| Dialog | A modal container that appears in response to a user action, temporarily interrupting the current workflow to request information or confirmation. | [dialog](references/dialog.md) |
| Expansion Panel | The Expansion Panel is a container component that manages multiple collapsible panels within a layout. | [expansion-panel](references/expansion-panel.md) |
| Floating Action Button | A floating action button presents the single most important action of a screen as a prominent, elevated button that can stay pinned to a bottom corner while the rest of the page scrolls beneath it. | [fab](references/fab.md) |
| Fieldset | A container that groups related form elements, including labels, controls, and helper text, to create accessible and organized input sections. | [fieldset](references/fieldset.md) |
| File Upload | Lets users choose one or more files for upload. | [file-upload](references/file-upload.md) |
| 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](references/icon.md) |
| Info Page | Provides a structured layout to display instructional content, messages, or status information, such as empty states or error notifications. | [info-page](references/info-page.md) |
| Inline Calendar | A compact calendar for selecting a single date or a date range within a monthly context. | [inline-calendar](references/inline-calendar.md) |
| Input | Provides a single-line field for users to enter text or color values. | [input](references/input.md) |
| 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](references/input-group.md) |
| Input Number | Allows users to enter numeric values with built-in validation and step controls. | [input-number](references/input-number.md) |
| Label | Provides an accessible caption for a user interface element, most commonly paired with input controls. | [label](references/label.md) |
| List | A container that displays a collection of related items in a structured format. | [list](references/list.md) |
| Listbox | A single-selection list component with support for grouped options, functionally similar to an HTML `<select>` element. | [listbox](references/listbox.md) |
| Menu | A structured list of options, optionally including headers, used to create navigational menus, context menus, or dropdowns. | [menu](references/menu.md) |
| Menubar | A horizontal bar of always-visible command menus, like the "File Edit View" menus found in desktop applications. | [menubar](references/menubar.md) |
| Month Picker | Allows users to select a month and year, either by typing it directly or by choosing from a popup of a year header and a twelve-month grid. | [month-picker](references/month-picker.md) |
| Navigation Menu | A horizontal navigation bar where items are either direct links or triggers that open a dropdown Menu. | [navigation-menu](references/navigation-menu.md) |
| Notifications | The Notification component is used to present important system feedback, status updates, or contextual information to the user. | [notifications](references/notifications.md) |
| One-Time Password Input | `x-h-otp` turns a native input into one or more groups of single-character cells for entering a verification code or PIN. | [otp](references/otp.md) |
| Pagination | Divides content into discrete pages, allowing users to navigate large datasets or collections more easily. | [pagination](references/pagination.md) |
| Popover | Displays supplementary information or content in a compact overlay without navigating away from the current page. | [popover](references/popover.md) |
| Progress | Visually represents the completion status of an ongoing operation, providing users with feedback on progress and expected duration. | [progress](references/progress.md) |
| Radio | A single-choice input that allows users to select one option from a set. | [radio](references/radio.md) |
| Range | Lets users select a numeric value, or a range between two values, by dragging a handle along a track. | [range](references/range.md) |
| Rating | Lets users view and set a star rating. | [rating](references/rating.md) |
| Select | Allows users to choose one or more items from a predefined list of options. | [select](references/select.md) |
| Separator | A simple visual divider used to separate content or sections within an interface. | [separator](references/separator.md) |
| Sheet | The sheet component is a side panel that overlays the window content and is shown on one side of the screen. | [sheet](references/sheet.md) |
| Sidebar | A vertical navigation panel used to present top-level application links or sections. | [sidebar](references/sidebar.md) |
| Skeleton | A placeholder component used to indicate that content is loading. | [skeleton](references/skeleton.md) |
| Slot Picker | An inline calendar that shows a configurable number of consecutive days (1 to 7, three by default), each with a vertical stack of selectable time slots. | [slot-picker](references/slot-picker.md) |
| Spinner | A visual indicator that signals an ongoing operation or process. | [spinner](references/spinner.md) |
| 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](references/step-indicator.md) |
| Switch | Allows users to toggle a binary state, such as true/false or on/off. | [switch](references/switch.md) |
| Table | Organizes data into rows and columns, with each row representing a single item and each column representing a specific attribute. | [table](references/table.md) |
| Tabs | Organizes content into multiple sections, displaying only one section at a time while keeping others easily accessible through a tabbed navigation interface. | [tabs](references/tabs.md) |
| Tag | A compact element used to display small pieces of information, labels, or metadata. | [tag](references/tag.md) |
| Text | Applies consistent typography styles to headings, paragraphs, single lines, and code blocks, ensuring a cohesive visual hierarchy and readability across the interface. | [text](references/text.md) |
| Textarea | Provides a multi-line input field for users to enter longer text. | [textarea](references/textarea.md) |
| Tile | A container that presents content, previews, or shortcuts in a compact, visually distinct format. | [tile](references/tile.md) |
| Time Picker | Allows users to select a specific time, providing a controlled and consistent input method for hours, minutes and seconds. | [time-picker](references/time-picker.md) |
| Toolbar | A container that groups actions (like buttons, inputs, or popovers) relevant to the current view. | [toolbar](references/toolbar.md) |
| Tooltip | A small pop-up that provides additional information or context about an interface element, displayed on hover. | [tooltip](references/tooltip.md) |
| Tree | Displays hierarchical data in a structured, expandable format, allowing users to explore nested items efficiently. | [tree](references/tree.md) |
| Week Picker | Allows users to select a whole ISO week, either by typing it directly or by choosing from a month calendar whose rows are weeks (Monday-first). | [week-picker](references/week-picker.md) |

### Charts

| Name | Description | Reference |
| ---- | ----------- | --------- |
| Area Chart | `x-h-chart-area` draws an area chart from a single reactive configuration object. | [area](references/area.md) |
| Bar Chart | `x-h-chart-bar` draws a bar chart from a single reactive configuration object. | [bar](references/bar.md) |
| 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](references/doughnut.md) |
| Line Chart | `x-h-chart-line` draws a line chart from a single reactive configuration object. | [line](references/line.md) |
| Pie Chart | `x-h-chart-pie` draws a pie chart from a single reactive configuration object. | [pie](references/pie.md) |
| Polar Area Chart | `x-h-chart-polar-area` draws a polar area chart from a single reactive configuration object. | [polar-area](references/polar-area.md) |
| Radar Chart | `x-h-chart-radar` draws a radar chart from a single reactive configuration object. | [radar](references/radar.md) |
| Scatter Chart | `x-h-chart-scatter` draws a scatter chart from a single reactive configuration object. | [scatter](references/scatter.md) |

### Layouts

| Name | Description | Reference |
| ---- | ----------- | --------- |
| Split | The split component provides a flexible layout for dividing content into resizable panels. | [split](references/split.md) |

### Utilities

| Name | Description | Reference |
| ---- | ----------- | --------- |
| Breakpoint Listener | Creates a listener that triggers actions when the viewport reaches specified breakpoint. | [breakpoint-listener](references/breakpoint-listener.md) |
| Chart Export | Utility functions for exporting a chart as an image. | [chart-export](references/chart-export.md) |
| Date Format | A behavior-only directive that renders a date value as a locale-aware date string into the element's text content, plus a `$dateFormat` magic that exposes the same formatting engine for use directly in Alpine expressions. | [date-format](references/date-format.md) |
| Focus | A behavior-only directive that programmatically sets focus on an element based on a specified condition. | [focus](references/focus.md) |
| Include | The include directive makes it easy to fetch and insert an external HTML fragment inside an element. | [include](references/include.md) |
| Responsive | A behavior-only directive that adds or removes classes based on the element's **own** width. | [responsive](references/responsive.md) |
| Template | The template directive makes it easy to insert and initialize an Alpine.js snippet inside a referenced `<template>` element. | [template](references/template.md) |
| Theme | Utility functions for retrieving and updating the color scheme. | [theme](references/theme.md) |

### Plugins

| Name | Description | Reference |
| ---- | ----------- | --------- |
| i18next | An optional plugin that binds the [i18next](https://www.i18next.com/) internationalization library to Alpine and Harmonia. | [i18next](references/i18next.md) |
| Lucide | An optional plugin that keeps [Lucide](https://lucide.dev) icons in sync with the Alpine/Harmonia lifecycle. | [lucide](references/lucide.md) |

### 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](references/utility-classes.md) |

### Migration

| Name | Description | Reference |
| ---- | ----------- | --------- |
| Migration | Breaking changes only, grouped by version - read before upgrading to a newer Harmonia version. | [migration](references/migration.md) |