Install Tavo.js UI - Tavo.js UI

Install the web package

Use Node.js 20.19+ or 22.12+. A generated Tavo.js application already has @tavojs/core, so install only @tavojs/ui, then use its bundled command to create the project-owned theme configuration.

BASH

bashnpm install @tavojs/ui
npx tavo-ui web init

Enable automatic theme generation

Merge tavoUi into the generated application configuration. Keep pagesDir, the starter stylesheet, diagnostics, build settings, and any plugins that are already present.

TS

tsimport { defineConfig } from "@tavojs/core/config";
import { tavoUi } from "@tavojs/ui/plugin";

export default defineConfig({
  pagesDir: "src/pages",
  cssEntries: ["src/styles.css"],
  diagnostics: {
    devOverlay: true,
    traces: false
  },
  plugins: [tavoUi()]
});

If plugins already contains entries, append tavoUi() instead of replacing them. No app-level theme import is required when injection is enabled. Set an explicit config path only when the project does not use the default filename.

Understand component and theme CSS

Normal root, grouped, and focused imports automatically load compiled component CSS.
tavoUi() supplies the project-generated theme variables.
Without the plugin, import @tavojs/ui/theme.css once to use the package default theme.
The /css entry points are equivalent aliases for tooling that prefers explicit CSS-safe paths.

TSX

tsximport { Button } from "@tavojs/ui/button";

export const SaveButton = () => {
  return <Button tone="primary">Save changes</Button>;
};

Package and runtime requirements

Tavo.js UI is a web component system for Tavo.js applications. Install its Core peer dependency explicitly when an application does not already include it. For a generated Tavo.js application, install only @tavojs/ui. Use Node.js 20.19+ or 22.12+ for the framework, Vite, and UI tooling.

BASH

bashnpm install @tavojs/ui
npx tavo-ui web init

The tavo-ui command is bundled with @tavojs/ui. Do not install or version its implementation package separately.
Components do not require a provider. Import them and render them through the normal Tavo.js application tree.
Published component entry points contain compiled styles; applications do not install Sass.
Component CSS and project theme CSS are separate: component imports supply structure, while the plugin or theme.css supplies variables.
@tavojs/ui 0.1.x declares @tavojs/core ^0.1.0 as its peer range.

Tavo.js UI plugin options

Control theme generation, injection, file output, logging, and development watching.

TS

tsimport { defineConfig } from "@tavojs/core/config";
import { tavoUi } from "@tavojs/ui/plugin";

export default defineConfig({
  pagesDir: "src/pages",
  cssEntries: ["src/styles.css"],
  diagnostics: {
    devOverlay: true,
    traces: false
  },
  plugins: [tavoUi({
    config: "tavo-ui.config.json",
    out: false,
    watch: true,
    silent: false,
    required: true,
    inject: true
  })]
});

API / option	Type	Default	Behavior
`config`	`string`	"`tavo-ui.config.json`"	Theme config path, relative to the project root unless absolute.
`out`	`string \| false`	false	Also writes generated CSS to this path. Unchanged content is not rewritten.
`watch`	`boolean`	true	Watches the config in development, regenerates it, invalidates the virtual CSS module, and reloads the page.
`silent`	`boolean`	false	Suppresses generation information and warnings.
`required`	`boolean`	true	Throws when the config is missing. false lets generation continue without project theme CSS.
`inject`	`boolean`	true	Adds the generated theme import to project `JavaScript` and `TypeScript` source modules.

What the plugin changes

During server rendering, the framework document receives the generated theme in a style record named tavo-ui.theme. During development and browser builds, the Vite integration serves the same CSS through the virtual @tavojs/ui/theme.css module.

Automatic injection applies only to JavaScript and TypeScript project source modules.
It excludes node_modules, dist, build output, files outside the project root, and tavo or Vite config modules.
A source file that already imports @tavojs/ui/theme.css is not modified again.
Malformed JSON, invalid theme values, and accessibility violations configured to fail all stop the build.

Choose one theme CSS delivery path

Component imports and theme variables are separate concerns. Root, grouped, and focused component imports load compiled component CSS automatically. The project plugin supplies project-owned theme variables; the package theme file supplies only the published default theme.

Recommended: enable tavoUi() and keep tavo-ui.config.json in the application. No application-level theme import is required.
Without the plugin: import @tavojs/ui/theme.css once to use the package default theme.
For an external pipeline: generate a physical CSS file with the CLI, then import that file once.
Do not combine project plugin injection with a generated physical theme import unless two theme definitions are intentional.
The /css component entry points are API-equivalent aliases; they do not replace theme CSS.

Know the plugin defaults before customizing it

Relative config and output paths resolve from the application root; absolute paths are accepted.
required: false allows an application to start without a config and produces no project theme CSS.
inject: false disables automatic source imports; the application must import the theme path intentionally.
watch: false disables config watching but does not disable generation during build startup.

TS

tstavoUi({
  config: "tavo-ui.config.json", // default
  out: false,                    // do not write a physical file
  watch: true,                   // watch config in development
  silent: false,                 // print generation and contrast messages
  required: true,                // fail when config is missing
  inject: true                   // attach the virtual theme import
})

Diagnose theme setup failures

A missing config throws tavo-ui: missing theme config when required remains true.
Invalid JSON fails while the plugin reads the config; schema and theme validation errors fail during generation.
A default-looking interface usually means the package theme was imported instead of the project-generated theme.
Missing variables usually mean neither the plugin, the default package theme, nor a generated CSS file was loaded.
Duplicate theme declarations usually mean more than one delivery path is active.