Recommended for new projects: Use Create to build your preset visually and get the command that applies it to your app.
WebJs UI is the component library for WebJs apps. Choose the setup that matches your starting point.
Use Create
Build your design system visually: pick the style, the colors, the radius, the fonts and the icons, and preview them on real components. Create prints an init --preset command that applies your choices to a WebJs app in one step.
Use the CLI
Use the CLI to scaffold a new project directly from the terminal:
npm create webjs@latest my-app
cd my-app && npm run dev
A new app is ready for the kit. webjs create writes the same components.json, lib/utils/cn.ts and theme that init would.
Its colors and fonts are the theme in styles/globals.css, so a preset from /ui/create repaints it:
Add the components you need:
Inside a WebJs app, webjs ui runs the same commands, since @webjsdev/ui ships with the WebJs CLI: webjs ui add button card dialog.
Existing Project
Run init in the app's root. It asks for a base color and the path of your Tailwind CSS file, then writes components.json, copies the cn() helper to lib/utils/cn.ts (with lib/utils/dom.ts beside it), and appends the theme tokens to the stylesheet.
Point it at the stylesheet your app compiles. Its default, styles/globals.css, is where webjs create puts the theme, imported from public/input.css, the stylesheet the app compiles. Running init again is safe: it keeps an existing components.json and helper files as they are unless you pass --overwrite.
Then add components:
The kit is copied into your app, not imported from a package at runtime. Tier-2 elements import @webjsdev/core, which every WebJs app already depends on, and add installs it when you add a Tier-2 component.
Manual Installation
Add Tailwind CSS
Components are styled using Tailwind CSS v4. A WebJs app made with webjs create already compiles public/input.css into public/tailwind.css, which its root layout links. Otherwise, follow the Tailwind CLI installation instructions and compile your entry the same way.
Add dependencies
The kit has one runtime dependency, @webjsdev/core, which the Tier-2 elements extend. A WebJs app already has it.
Configure import aliases
WebJs apps use the imports field of package.json for their aliases. Node and Bun resolve it at runtime with no build step and no tsconfig.json paths.
{
"imports": {
"#*": "./*"
}
}
That one entry makes every top-level folder an alias: #components/ui/button.ts, #lib/utils/cn.ts. See the package imports guide for the details.
Configure styles
Add the following to the stylesheet your app compiles, after @import "tailwindcss";. You can learn more about using CSS variables for theming in the theming section.
@import "tailwindcss";
/* @webjsdev/ui theme */
/* Generated by `webjsui init`. Edit freely - you own this. */
@theme inline {
--radius-sm: calc(var(--radius) * 0.6);
--radius-md: calc(var(--radius) * 0.8);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) * 1.4);
--radius-2xl: calc(var(--radius) * 1.8);
--radius-3xl: calc(var(--radius) * 2.2);
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-card: var(--card);
--color-card-foreground: var(--card-foreground);
--color-popover: var(--popover);
--color-popover-foreground: var(--popover-foreground);
--color-primary: var(--primary);
--color-primary-foreground: var(--primary-foreground);
--color-secondary: var(--secondary);
--color-secondary-foreground: var(--secondary-foreground);
--color-muted: var(--muted);
--color-muted-foreground: var(--muted-foreground);
--color-accent: var(--accent);
--color-accent-foreground: var(--accent-foreground);
--color-destructive: var(--destructive);
--color-destructive-foreground: var(--destructive-foreground);
--color-border: var(--border);
--color-input: var(--input);
--color-ring: var(--ring);
--color-chart-1: var(--chart-1);
--color-chart-2: var(--chart-2);
--color-chart-3: var(--chart-3);
--color-chart-4: var(--chart-4);
--color-chart-5: var(--chart-5);
--color-sidebar: var(--sidebar);
--color-sidebar-foreground: var(--sidebar-foreground);
--color-sidebar-primary: var(--sidebar-primary);
--color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
--color-sidebar-accent: var(--sidebar-accent);
--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
--color-sidebar-border: var(--sidebar-border);
--color-sidebar-ring: var(--sidebar-ring);
}
/* Custom variants for component data attributes */
@custom-variant data-open (&:where([data-state="open"]));
@custom-variant data-closed (&:where([data-state="closed"]));
@custom-variant data-checked (&:where([data-state="checked"]));
@custom-variant data-unchecked (&:where([data-state="unchecked"]));
@custom-variant data-active (&:where([data-state="active"]));
@custom-variant data-disabled (&:where([data-disabled]:not([data-disabled="false"])));
@custom-variant data-selected (&:where([data-selected="true"]));
@custom-variant data-horizontal (&:where([data-orientation="horizontal"]));
@custom-variant data-vertical (&:where([data-orientation="vertical"]));
@custom-variant dark (&:is(.dark *));
@keyframes accordion-down {
from { height: 0; }
to { height: var(--accordion-panel-height, auto); }
}
@keyframes accordion-up {
from { height: var(--accordion-panel-height, auto); }
to { height: 0; }
}
:root {
--radius: 0.625rem;
--background: oklch(1 0 0);
--foreground: oklch(0.145 0 0);
--card: oklch(1 0 0);
--card-foreground: oklch(0.145 0 0);
--popover: oklch(1 0 0);
--popover-foreground: oklch(0.145 0 0);
--primary: oklch(0.205 0 0);
--primary-foreground: oklch(0.985 0 0);
--secondary: oklch(0.97 0 0);
--secondary-foreground: oklch(0.205 0 0);
--muted: oklch(0.97 0 0);
--muted-foreground: oklch(0.556 0 0);
--accent: oklch(0.97 0 0);
--accent-foreground: oklch(0.205 0 0);
--destructive: oklch(0.577 0.245 27.325);
--destructive-foreground: oklch(0.97 0.01 17);
--border: oklch(0.922 0 0);
--input: oklch(0.922 0 0);
--ring: oklch(0.708 0 0);
--chart-1: oklch(0.81 0.10 252);
--chart-2: oklch(0.62 0.19 260);
--chart-3: oklch(0.55 0.22 263);
--chart-4: oklch(0.49 0.22 264);
--chart-5: oklch(0.42 0.18 265);
--sidebar: oklch(0.985 0 0);
--sidebar-foreground: oklch(0.145 0 0);
--sidebar-primary: oklch(0.205 0 0);
--sidebar-primary-foreground: oklch(0.985 0 0);
--sidebar-accent: oklch(0.97 0 0);
--sidebar-accent-foreground: oklch(0.205 0 0);
--sidebar-border: oklch(0.922 0 0);
--sidebar-ring: oklch(0.708 0 0);
}
.dark {
--background: oklch(0.145 0 0);
--foreground: oklch(0.985 0 0);
--card: oklch(0.205 0 0);
--card-foreground: oklch(0.985 0 0);
--popover: oklch(0.205 0 0);
--popover-foreground: oklch(0.985 0 0);
--primary: oklch(0.922 0 0);
--primary-foreground: oklch(0.205 0 0);
--secondary: oklch(0.269 0 0);
--secondary-foreground: oklch(0.985 0 0);
--muted: oklch(0.269 0 0);
--muted-foreground: oklch(0.708 0 0);
--accent: oklch(0.371 0 0);
--accent-foreground: oklch(0.985 0 0);
--destructive: oklch(0.704 0.191 22.216);
--destructive-foreground: oklch(0.58 0.22 27);
--border: oklch(1 0 0 / 10%);
--input: oklch(1 0 0 / 15%);
--ring: oklch(0.556 0 0);
--chart-1: oklch(0.81 0.10 252);
--chart-2: oklch(0.62 0.19 260);
--chart-3: oklch(0.55 0.22 263);
--chart-4: oklch(0.49 0.22 264);
--chart-5: oklch(0.42 0.18 265);
--sidebar: oklch(0.205 0 0);
--sidebar-foreground: oklch(0.985 0 0);
--sidebar-primary: oklch(0.488 0.243 264.376);
--sidebar-primary-foreground: oklch(0.985 0 0);
--sidebar-accent: oklch(0.269 0 0);
--sidebar-accent-foreground: oklch(0.985 0 0);
--sidebar-border: oklch(1 0 0 / 10%);
--sidebar-ring: oklch(0.439 0 0);
}
@layer base {
/* Focus: a themed, keyboard-only (:focus-visible), never-removed outline, in
the --ring colour, applied globally. `outline-ring/50` themes only the
COLOUR and leaves outline-style: auto, which the browser draws as its OWN
ring (it can look thick/white and ignore the colour). So force a SOLID
outline on focus, at a consistent width + offset, so the themed --ring/50
colour actually renders the same on every element. A shadow-DOM component
sets its own focus (a document rule cannot cross the shadow boundary). */
* {
@apply border-border outline-ring/50;
}
:focus-visible {
outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent);
outline-offset: 2px;
}
/* Native <select> options paint transparent over the browser popup when no
rule applies, so in dark mode Chrome's dark popup plus the inherited text
colour makes every unselected option disappear. Canvas / CanvasText are
the system colours the browser would have painted anyway, so this stops
relying on inheritance to pull them through. Two ELEMENT selectors
(specificity 0,0,2) and no wrapper requirement on purpose: a bare
<select class=${nativeSelectClass()}> with no wrapper is legitimate, and
any single class overrides this. */
select option,
select optgroup {
background-color: Canvas;
color: CanvasText;
}
}
/* @webjsdev/ui theme end */
Add a cn helper
Components merge their classes with cn(), a small hand-written class merger in place of clsx and tailwind-merge, plus onBeforeCache(), a client-only helper kept in its own file. Print each one and save its source, the lines after the # lib/... header, under lib/utils/:
Save the first as lib/utils/cn.ts and the second as lib/utils/dom.ts, beside it. The components import dom.ts as the sibling of the cn() file, so keep the two together.
Create a components.json file
Create a components.json file in the root of your project.
{
"$schema": "https://ui.webjs.dev/schema.json",
"style": "default",
"tailwind": {
"css": "public/input.css",
"baseColor": "neutral",
"cssVariables": true
},
"aliases": {
"components": "components",
"utils": "lib/utils/cn",
"ui": "components/ui",
"lib": "lib"
}
}
The aliases are folders relative to the project root, and utils names the cn() file without its extension. See components.json for every key.
That's it
You can now start adding components to your project.