Composable UI building blocks you can install, adapt, or copy into your project. Familiar to use, polished by default.
Harmo is a CSS-first UI library for dashboards and applications. Every component is a native HTML element with one class, styled by plain CSS and themed with custom properties. Use it as HTML and CSS, through its React components, or by copying the source into your project and making it yours. Its name comes from the Greek idea of fitting things together: small, useful pieces that compose into more capable interfaces.
Status: Early development, at
0.x: APIs may still change between releases.
Website · Components · Playground · Philosophy · For AI agents · Changelog · Contributing
- Composable building blocks. Each component has one clear job, and they fit together without knowing your product: Popup and Listbox make a Select, and Field arranges any control's label, description, and error.
- Native first. Real
<button>,<input>, and<a>elements, with their native attributes, keyboard behavior, and semantics preserved. - One markup for HTML and React. The React components render exactly the HTML in the docs, which a test checks, and do what the example scripts do.
- Themeable without fighting CSS. A palette plus semantic roles, exposed
as
--harmo-*custom properties, with low-specificity selectors so your overrides win. - Polished by default. Considered spacing, focus states, and motion, with reduced-motion alternatives.
- Ready for agents. Every component page opens with a Contract table, and llms.txt indexes the docs and the rules for using them.
The principles behind these choices are in docs/philosophy.md.
There are two ways to use Harmo in a project. Choose one.
Install it, and get updates through your package manager:
bun add @harmo-ui/css @harmo-ui/react
# or: npm install @harmo-ui/css @harmo-ui/react@harmo-ui/react needs React 19.3
or later. For HTML and CSS alone, install only
@harmo-ui/css, or load it from a
CDN as below.
Copy it, and make it yours:
npx harmo-ui add tabsharmo-ui copies a component, its styles,
and what it needs into your project, so you can change anything. Copied files don't
get updates on their own.
Load the full stylesheet, tokens and every component, then use the .h*
classes:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@harmo-ui/css@0.9/dist/index.css" />
<button class="hbutton" type="button">
<span class="hbutton-label">Save changes</span>
</button>
<button class="hbutton" data-variant="secondary" type="button">
<span class="hbutton-label">Cancel</span>
</button>
<a class="hlink" href="/reports">View reports</a>To load only what you need, import tokens.css once, then each component:
@import "@harmo-ui/css/tokens.css";
@import "@harmo-ui/css/button.css";
@import "@harmo-ui/css/link.css";Component files use the --harmo-* properties without defining them, so
tokens.css is required. Some components also need companion files, such as
popup.css and listbox.css for select.css; see
Loading the CSS.
Components with behavior, such as Select, Tabs, and Tooltip, need a script that keeps their attributes current. Each page's "What a script does" lists it, and the playground's example scripts show how. The React components do it for you.
@harmo-ui/react renders the same markup and does what the scripts do. Load the
CSS once, then use the components:
import "@harmo-ui/css";
import { Button, Field, Input, Link } from "@harmo-ui/react";
<Button type="submit">Save changes</Button>
<Button variant="secondary">Cancel</Button>
<Link href="/reports">View reports</Link>
<Field label="Email address" description="We'll send your receipt here.">
<Input name="email" type="email" />
</Field>Set your router's link component and your framework's image component once,
at the root. Every link a component renders uses the link component: Link,
Button and Card with href, TabLink, FilterBarItem with href,
NavigationMenuLink and NavigationMenuRow, Pagination with href, SidebarItem
and SidebarSubItem, and DataTable's rowHref; Avatar uses the image component.
In the Next.js App
Router, do it in a Client Component, because a Server Component can't pass
functions to one, and wrap your root layout's {children} in it:
"use client";
import NextImage from "next/image";
import NextLink from "next/link";
import { HarmoProvider } from "@harmo-ui/react";
export default function Providers({ children }: { children: React.ReactNode }) {
return (
<HarmoProvider linkComponent={NextLink} imageComponent={NextImage}>
{children}
</HarmoProvider>
);
}Harmo builds in no text: every word a component shows or announces comes from you, so an app in any language reads as one. Each component page's React section lists its props.
| Group | Components |
|---|---|
| Actions | Button, Copy Button, Link |
| Forms | Calendar, Checkbox, Combobox, Composer, Date Picker, Drop Zone, Field, File Input, File List, Input, Mentions, OTP Input, Password Input, Phone Input, Radio, Search, Segmented Control, Select, Settings List, Switch, TextArea, Time Picker |
| Overlays | Dialog, Drawer, Dropdown Menu, Launcher, Listbox, Popup, Tooltip |
| Navigation | Account Menu, Breadcrumb, Command Menu, Footer, Header, Language Picker, Menu Button, Navigation Menu, Pagination, Sidebar, Table of Contents, Tabs |
| Data | Date Filter, Filter Bar, Filter Chip, Filters, Selection Bar, Table, Toolbar |
| Feedback | Banner, Empty State, Meter, Spinner, Toast |
| Display | Accordion, Avatar, Badge, Card, Conversation, Kbd, Message, Prose, Section, Showcase Card, Stat, Status, Tag, Tag List |
| Icons | Icons, ChevronToArrow, Expand Chevron |
Every page has the same sections: a Contract table, copyable markup, the options, appearance and states, accessibility, what a script does, the React component, and the tokens it reads.
A pattern is an arrangement of components for a whole task, such as signing in.
Copy one into your app with npx harmo-ui add <pattern>, then change it as your
own code; each comes in React and in HTML. In React, a form takes action, a
form action such as a Next.js server action, and works without JavaScript.
| Pattern | Does |
|---|---|
| Sign-in Form | Signs someone in with their email and password, or with another account, such as Google, with a link to reset the password and, if you like, a code as a second step |
| Sign-up Form | Creates an account with a name, an email, and a password, or with another account, such as Google, and, if you like, confirms the email by a link or a code |
| Reset Password | Sends a link to reset a forgotten password, then sets a new one |
| Account Forms | Signs someone in, creates an account, or sends a link to reset a password, switching between them in place, such as in a Dialog |
| Verify Code | Asks for a one-time code, such as a sign-in's second step or one that confirms an email, with a new code after a wait |
| Chat | A conversation with an assistant: an AI chat, a copilot beside your app's content, or a support chat that opens from a corner |
| Globe | The world in dots, turning slowly, with routes arcing between places, drawn with three.js |
| Kanban | A board whose cards are dragged from column to column, or moved from each card's menu, saving each move with your app |
| Contact Form | Lets people reach your team: a message, a sales inquiry, a support request, and help with an order |
Harmo's colors, type, and shapes are --harmo-* custom properties. The quickest
way to change its color is an accent. For your own brand color, generate a
theme. Any token can also be set by hand.
data-harmo-accent recolors everything inside it, in light and dark mode: text
and links in the primary, checked marks and their tints, buttons, switches, and
the focus ring.
<html data-harmo-accent="blue">The accents are purple (the default), blue, teal, green, amber, red,
pink, and mono, which is black, or near-white in dark mode. Each has the
same contrast as the purple in every role, so text, and the text on buttons,
pass WCAG AA in both modes. Put the attribute on any element to recolor only
that part of the page. index.css includes accents.css, and
npx harmo-ui add copies it with tokens.css; with per-component imports,
load accents.css after tokens.css.
npx harmo-ui theme "#0f75b6"That writes harmo-theme.css: your color in every role, in light and dark
mode, adapted from the nearest accent at the same contrast, so text and buttons
pass WCAG AA too. A color too light for white text, such as a bright yellow, is
darkened for text and buttons, and the file says so. A gray's tint, behind the
page you're on in Pagination, is lightened until the gray reads on it, and the
gray is darkened only if that isn't enough. It's ordinary CSS: change
any line you like, since your values win over Harmo's wherever the file loads.
In a project with a harmo.css from npx harmo-ui add, it's added there.
Token names say what is colored, then the variant, then the state
(--harmo-color-primary-hover). --harmo-color-* names are semantic roles;
plain names such as --harmo-purple are the palette they default to, so you can
re-theme by changing roles without touching components. The font is the
system's by default. To match an existing app, set it once:
:root {
--harmo-font-family: "Helvetica Neue", Helvetica, sans-serif;
}Token defaults are declared on :where(:root), and accents with :where()
too, so your overrides on :root win whichever stylesheet loads last, over an
accent on <html> as well. An accent on a section sets its colors on that
section, which win inside it over what it inherits from :root: to change one,
override it on the section. For a local theme, override the role on the
component or a containing element instead of :root. Tokens built from another
token are worked out on :root, so a local override doesn't reach them:
redeclare those in the same place.
.dark-panel {
--harmo-color-focus: #8ab4ff;
--harmo-focus-outline: 2px solid var(--harmo-color-focus);
}The built tokens are --harmo-focus-outline; the primary fills;
--harmo-color-on-primary and --harmo-color-on-danger; the link, input,
switch, icon, status, and secondary-button tokens;
--harmo-button-font-weight; --harmo-card-padding; and the button and
chevron durations; see tokens.css. A role is built from its palette color
too, such as --harmo-color-text from --harmo-black, so change the role
itself. Each component page lists every token it reads.
To set your primary color by hand, rather than with harmo-ui theme, set its
whole family, as a theme and every accent do: --harmo-color-primary,
--harmo-color-primary-hover, --harmo-color-primary-active, and
--harmo-color-primary-tint; the fills behind white text,
--harmo-color-primary-fill, -fill-hover, and -fill-active, with
--harmo-color-on-primary for that text and
--harmo-switch-thumb-color-background; --harmo-color-focus, with
--harmo-focus-outline redeclared beside it; and --harmo-link-color-text,
--harmo-link-visited-color-text, and --harmo-link-hover-text-decoration.
Only the light fills follow the primary by themselves: the focus ring and
links keep Harmo's purple until you set them.
Harmo's colors come in light and dark pairs, through CSS's light-dark(). A
page stays light until it opts in with color-scheme, even on a dark system:
:root { color-scheme: dark; } /* always dark */
:root { color-scheme: light dark; } /* follows the system */
.sidebar { color-scheme: dark; } /* one part of the page */Every accent, and every theme harmo-ui theme writes, covers both modes. To set
colors by hand for both, give each as a pair, such as
light-dark(#0f75b6, #30aed9). Button and Switch use the
--harmo-color-primary-fill tokens rather than the primary: a dark-mode primary
light enough to read as text on a dark page is too light to sit behind white
text.
Harmo targets current versions of Chrome, Edge, Firefox, and Safari. It uses
the popover attribute, CSS anchor positioning (in all major browsers since
January 2026), field-sizing: content (since June 2026), @starting-style,
and :has(); see
Browser features used.
Two playgrounds show every component and variation, with the code to copy: one in plain HTML and CSS, the other built with the React components. Both open straight from disk, no server needed:
mise run build:playground # then open examples/html/dist/index.html
mise run build:react-playground # then open examples/react/dist/index.htmlllms.txt indexes the docs and the rules for writing Harmo markup and using the React components. Every component page opens with a Contract table: the files to load, the elements and parts, the required attributes, what must be unique, and what a script does.
CONTRIBUTING.md covers setup with mise and Bun, the project's layout, and how the CSS, docs, examples, and tests fit together.
Harmo is built and maintained by Imran Hajiyev, extracted from components originally built for production dashboard work, so every component here has already survived real use.
- X: x.com/imranhajiyev
- LinkedIn: linkedin.com/in/imranhajiyev