| name | ktui-install |
| description | Install, configure, and initialize KtUI (Keenthemes Tailwind UI) in any project. Use this skill when setting up KtUI for the first time, adding it to a new project, configuring Tailwind for KtUI, or troubleshooting initialization issues.
|
KtUI Installation & Setup
1. Install the package
npm install @keenthemes/ktui
2. Tailwind CSS config
Add KtUI source paths to your Tailwind content array so Tailwind scans KtUI classes:
module.exports = {
content: [
'./node_modules/@keenthemes/ktui/src/**/*.{ts,js}',
],
};
3. Import styles
Import KtUI's built-in CSS (or use your own build of the source):
import '@keenthemes/ktui/dist/styles.css';
4. Import and initialize components
import { KTComponents } from '@keenthemes/ktui';
KTComponents.init();
Per-framework placement
| Framework | Where to call KTComponents.init() |
|---|
| Vanilla JS | DOMContentLoaded listener or <script> at bottom of <body> |
| React | useEffect(() => { KTComponents.init(); }, []) |
| Vue 3 | onMounted(() => { KTComponents.init(); }) |
| Next.js | Inside a client component's useEffect (never during SSR) |
| Nuxt | Inside onMounted or a client-only plugin |
| Laravel Livewire | Automatic — livewire:navigate triggers re-init |
SSR safety
Never call init() during server-side rendering. Guard with:
if (typeof window !== 'undefined') {
KTComponents.init();
}
Dynamic content (SPAs, lazy-loaded views)
After injecting new KtUI markup (route change, AJAX-loaded modal, etc.), re-initialize:
KTComponents.init();
import { KTModal } from '@keenthemes/ktui';
KTModal.init();
5. TypeScript types
All config and interface types are exported from the package root — no deep paths:
import type {
KTModalConfigInterface,
KTDataTableConfigInterface,
KTDropdownConfigInterface,
KTSelectConfigInterface,
KTToastConfigInterface,
} from '@keenthemes/ktui';
6. CSS variables (theming)
KtUI requires CSS custom variables defined on :root. At minimum:
:root {
--background: oklch(1 0 0);
--foreground: oklch(14.1% 0.005 285.823);
--primary: oklch(62.3% 0.214 259.815);
--primary-foreground: oklch(1 0 0);
--border: oklch(92% 0.004 264.531);
--radius: 0.5rem;
}
See the ktui skill or ktui.io/docs/theming for the full variable list.
7. Dark mode setup
Add the Tailwind dark variant:
@custom-variant dark (&:is(.dark *));
Override the same CSS variables under .dark:
.dark {
--background: oklch(14.1% 0.005 285.823);
--foreground: oklch(98.5% 0 0);
--primary: oklch(70.7% 0.165 254.624);
--primary-foreground: oklch(14.1% 0.005 285.823);
}
Toggle .dark on <html> or use the KTThemeSwitch component.
8. Troubleshooting
| Problem | Cause | Fix |
|---|
| Components not interactive | init() not called | Call KTComponents.init() after DOM ready |
| Tailwind classes not applied | Missing content path | Add ktui/src/** to Tailwind config |
| Styles look broken | CSS variables not defined | Define required variables on :root |
| SSR hydration mismatch | init() on server | Guard with typeof window !== 'undefined' |
| Re-init after navigation | SPA didn't re-init | Call KTComponents.init() after route change |
Documentation
