Getting Started
Install and integrate @ziteox/ui in a Ziteox application.
Getting Started
Install and use @ziteox/ui in a Ziteox application.
Prerequisites
- Node.js 18+
- pnpm 9+
- React 18 or 19
Installation
From the monorepo (local development)
In ziteox-forge:
pnpm install
pnpm buildIn a consuming app package.json:
{
"dependencies": {
"@ziteox/ui": "workspace:*"
}
}From a registry (when published)
pnpm add @ziteox/ui next-themes motion web-haptics react react-domPeer dependencies must be installed in the consuming app.
Minimal setup
1. Dark mode CSS
ThemeProvider toggles the dark class on document.documentElement.
:root {
color-scheme: light dark;
background: #ffffff;
color: #0a0a0a;
}
.dark {
background: #0a0a0a;
color: #fafafa;
}2. Theme provider
import { ThemeProvider } from "@ziteox/ui";
export function App({ children }: { children: React.ReactNode }) {
return <ThemeProvider>{children}</ThemeProvider>;
}ThemeProvider defaults:
attribute="class"defaultTheme="system"enableSystem={true}disableTransitionOnChange={true}
Pass any ThemeProviderProps from next-themes to override.
3. Use components
import { ThemeToggle, HamburgerButton, BrandCredit } from "@ziteox/ui";
import { useState } from "react";
export function Header() {
const [menuOpen, setMenuOpen] = useState(false);
return (
<header>
<HamburgerButton
isOpen={menuOpen}
onOpenChange={setMenuOpen}
className="lg:hidden"
/>
<ThemeToggle />
</header>
);
}
export function Footer() {
return <BrandCredit variant="engineered" />;
}Domain subpath imports
Optional explicit imports:
import { ThemeToggle } from "@ziteox/ui/theme";
import { HamburgerButton } from "@ziteox/ui/navigation";
import { BrandCredit } from "@ziteox/ui/branding";Root import @ziteox/ui is preferred for most apps.
Next.js App Router
Components with "use client" in source:
ThemeProviderThemeToggleAnimatedThemeTogglerHamburgerButton
Import from client components or client layouts.
BrandCredit has no "use client" directive and can render in Server Components.
Local playground
cd ziteox-forge
pnpm install
pnpm build
pnpm --filter playground devOpen the Vite dev server URL. The playground imports from @ziteox/ui source via alias.
Troubleshooting
| Issue | Likely cause | Fix |
|---|---|---|
| Theme toggle does nothing | Missing ThemeProvider | Wrap app root |
| Flash on hydration | Expected before mount | ThemeToggle renders placeholder until mounted |
motion not found | Missing peer | pnpm add motion |
useTheme error | Missing provider | Add ThemeProvider |
| Styles look unstyled | Missing global .dark CSS | Add CSS from step 1 |
| Hamburger invisible on light bg | Glass button styled for dark headers | Pass className or use on dark background |