--- title: Integration Guide description: Required setup, optional dependencies, asset publishing, and verification checklist for embedding WireKit in your app visibility: guest draft: false --- # Integration Guide The complete setup reference: required dependencies, browser baseline, asset publishing, optional features, and a verification checklist. The [Getting Started](/getting-started) recipe gets you to a working install in the common case — come here when you need to understand the moving parts in detail or debug a specific step. ## Browser Support WireKit's supported-browser baseline is **pinned to [Tailwind CSS v4's official requirements](https://tailwindcss.com/docs/compatibility)** — whenever Tailwind raises its baseline, WireKit follows in the same release. There is no separate "WireKit browser matrix" to track. | Browser | Minimum version | Released | |---------|-----------------|----------| | **Chrome** | 111 | March 2023 | | **Edge** | 111 | March 2023 (Chromium-based) | | **Safari** | 16.4 | March 2023 | | **Firefox** | 128 | July 2024 | **What this means for your app:** - If your application already runs on Tailwind CSS v4 (which is a required dependency), you are automatically within WireKit's supported range. No separate compatibility check is needed. - WireKit ships **no polyfills**, **no vendor-prefix fallbacks**, and **no shims** for browsers that Tailwind has dropped. Components may visually degrade or break in older browsers. - WireKit freely uses modern CSS features that are covered by the Tailwind baseline — including `@property`, `color-mix()`, `contain: inline-size`, and `min()`/`max()`. You can rely on these in your own code inside WireKit components. - Not every modern feature is covered. `@starting-style`, `field-sizing: content`, `text-wrap: balance`, native CSS nesting and `round()` each first shipped above one of the minimum versions in the table — they are progressive enhancement, not floor. Where WireKit uses one, it sits behind an `@supports` test and adds polish that nothing depends on, so a browser at the minimum version renders the component without it. Detect them the same way in your own code instead of assuming them. - If your audience still includes users on older browsers (e.g. corporate intranets pinned to Chrome 108), WireKit is not the right fit. Consider staying on Tailwind v3 + a compatible UI kit. ::: tip The only officially supported configuration is **Tailwind v4 + WireKit on a browser from the table above**. Any other combination is unsupported and untested. ::: ## Required Setup ### 1. Composer ```bash # 1. Pull WireKit + Livewire v4 (a hard dependency — Alpine.js is bundled # with Livewire, so no separate npm install for Alpine is needed). The # two icon packages ensure renders the heroicons set # used internally by buttons / dropdowns / overlays. composer require pushery/wirekit blade-ui-kit/blade-icons blade-ui-kit/blade-heroicons ``` ### 2. Blade Directives Add both directives to your app layout, `@wirekitScripts` before `@livewireScripts`: ```blade @wirekitStyles {{-- Design tokens, CSS variables, keyframe animations --}} @vite(['resources/css/app.css', 'resources/js/app.js']) {{ $slot }} @wirekitScripts {{-- WireKit Alpine component registrations (BEFORE @livewireScripts) --}} @livewireScripts {{-- Boots Alpine + Livewire's runtime --}} ``` **The invariant is about EXECUTION, not tag order.** WireKit's Alpine factories have to be registered before `Alpine.start()` runs, and `@wirekitScripts` emits its tag with `defer` — a deferred script runs after parsing and before `DOMContentLoaded`, wherever its tag sits. In a Livewire application the requirement is therefore met either way, and swapping the two directives changes nothing measurable. The order above is still the one to write: it says what depends on what, and it is the arrangement every other page here assumes. **Where it genuinely breaks is anything that runs the bundle LATE** — an `async` attribute instead of `defer`, a file injected at runtime, a bundler that drops the `defer`, or a non-Livewire setup that starts Alpine earlier. If every `wirekit*` factory is missing at once, look there before you look at the order of two lines. **`@wirekitStyles`** loads `wirekit.css` — contains: - ~70 CSS custom properties (colors, spacing, radius, shadows, fonts) - Dark mode token switching via `.dark` class on `` - Keyframe animations (`wk-skeleton`, `wk-progress-indeterminate`) - `prefers-reduced-motion` guard for all animations - `[x-cloak] { display: none !important }` — see below ::: info `x-cloak` is covered — the rule ships with WireKit Alpine hides nothing for `x-cloak`; it removes the attribute once it has initialized, and the hiding has to come from CSS. Many WireKit components rely on it to stay invisible until Alpine boots, so `wirekit.css` ships the rule and `@wirekitStyles` is what delivers it. Worth knowing if you go looking for it: `@wirekitStyles` emits its own `` to `wirekit.css`. The rule therefore lives in that file — **not** in your Vite bundle, and grepping `public/build/assets/app-*.css` for it finds nothing whether everything is wired up correctly or not. Check the served `wirekit.css` instead, or the published copy at `public/vendor/wirekit/wirekit.css`. You only need to write the rule yourself if you deliberately load neither — no `@wirekitStyles` and no import of `wirekit.css`. In that case you have no design tokens either, and cloaked elements flashing on load is the smaller of the two symptoms. ::: **`@wirekitScripts`** loads `wirekit.js` — contains: - All Alpine.js component registrations (`wirekitModal`, `wirekitDropdown`, etc.) - Floating UI positioning (tooltips, popovers, dropdowns) - Focus trap utility (modals, drawers, alert dialogs) - Overlay scroll lock (reference-counted) #### The overlay container Every teleported panel — modal, drawer, dropdown, tooltip — lands inside one labeled region, `
`. Without it those panels sit outside every landmark, which an accessibility audit flags and a screen-reader user experiences as content that belongs nowhere. **You do not have to do anything.** `@wirekitScripts` creates the container, names it in the page's language, and re-creates it after a `wire:navigate`. **Writing it yourself is supported, and it is the sturdier of the two routes.** Put it in your layout and it sits in the markup Livewire morphs, so it is never briefly absent and no navigation timing has to be right: ```blade {{-- 1. Optional. WireKit adopts this container instead of creating its own, and fills in the role and the localized name if you left them out. --}}
{{-- 2. The scripts still come after it. --}} @wirekitScripts ``` A `role` or an `aria-label` you write yourself is left alone — including `aria-labelledby`, so a container pointed at a heading keeps its name. Only what is missing gets filled in, because a label you wrote is one you translated. **To supply the name yourself** — for a locale WireKit does not ship, or wording your product prefers — put it on any ` ``` ### The routes that serve WireKit's own files `@wirekitStyles` and `@wirekitScripts` fall back to package routes when the assets are not published. Those routes **run no middleware**, and that is deliberate rather than an oversight. They serve a static file from the package directory: no session is read, no user is looked at, and the reply declares `public, max-age=31536000, immutable`. Under Laravel's `web` group every one of those replies also carried a session cookie — and a shared cache invited to keep a response for a year may hand it to the next visitor with the cookie still attached. Removing the group is what makes the year-long directive honest and the files genuinely cacheable by a CDN. **If you need middleware on them, name it** in `wirekit.assets.middleware`: ```php // 1. config/wirekit.php — an empty array (the default) means no middleware. 'assets' => [ 'middleware' => ['throttle:asset-serving'], ], ``` A bare string works too and is cast for you, so `'middleware' => 'web'` does not silently produce a route with none. **Before you add `web` back:** it is the one value that reintroduces the cookie. If what you actually want is a rate limit, a geo-block or a log line, name that middleware instead — the session is almost never the thing you were after. Publishing the assets (`vendor:publish --tag=wirekit-assets`) makes the question moot for production: the files are then served by your web server and never reach Laravel at all. ### 3. Tailwind CSS v4 Source Scanning **CRITICAL:** WireKit components use Tailwind utility classes internally. Your app's Tailwind build MUST scan WireKit's Blade templates, or the component styles will be missing. In your `resources/css/app.css`: ```css /* 1. Pull in Tailwind v4 — provides `@source`, `@theme`, and the utility-class compiler. */ @import "tailwindcss"; /* 2. Register WireKit's published Blade templates as a Tailwind source directory. Without this line, the utility classes WireKit components emit at runtime never reach the compiled CSS — buttons render without backgrounds, inputs without padding. */ @source "../../vendor/pushery/wirekit/resources/views/**/*.blade.php"; ``` **Without this line**, components render as unstyled HTML — tables have no borders, inputs have no padding, buttons have no backgrounds. > **Tip:** Both setup paths work in v1.3.0+: > > 1. **`@wirekitStyles` Blade directive** (the path documented above) — emits a `` tag straight to the package's compiled CSS. Fastest path, no Tailwind compile step required. > 2. **`@import '../../vendor/pushery/wirekit/dist/wirekit.css'`** in `resources/css/app.css` — Tailwind v4 picks up the variables on its next compile. Useful when you want a single bundled CSS file from Vite. > > Either path resolves; pick whichever fits your build pipeline. Pre-v1.3.0 versions used Tailwind's `@theme {}` compiler directive, which browsers skipped as an unknown at-rule when loaded via `` — that's now fixed (the file ships with `:root {}` / `.dark {}` blocks directly). ### 4. Alpine.js — comes via Livewire v4 WireKit declares `livewire/livewire ^4.0` as a hard composer dependency. Livewire v4 bundles Alpine.js and starts it for you when `@livewireScripts` runs — so a separate Alpine install is **not needed and not recommended**: - ❌ Do NOT `npm install alpinejs` - ❌ Do NOT `import Alpine from 'alpinejs'` in your `app.js` - ❌ Do NOT call `Alpine.start()` manually - ✅ Just emit `@wirekitScripts` THEN `@livewireScripts` in your layout (per Step 2). Livewire's bundle starts Alpine; WireKit's components register on `alpine:init` before that happens because the directives execute in document order. The full reasoning + a complete copy-pasteable layout file lives on the [Getting Started](/getting-started#layout-setup) page. ### Dark-mode `dark:` utilities in your own markup WireKit's components switch their colors automatically via the `.dark` class — the `--color-wk-*` tokens flip in the `.dark {}` block of `wirekit.css`, so you never write `dark:` utilities on a WireKit component. But if **your own** markup uses Tailwind `dark:` utilities (e.g. `
`), add one line to `resources/css/app.css` so they follow the `.dark` **class** your theme toggle sets on `` — not the OS `prefers-color-scheme`: ```css /* 1. Pull in Tailwind v4. */ @import "tailwindcss"; /* 2. Make Tailwind's `dark:` variant key off a `.dark` CLASS on a parent (the same class WireKit + your toggle set on ), not the OS-level prefers-color-scheme. Without this, your own `dark:` utilities react only to the OS setting, so a manual light/dark switch appears to do nothing for them. */ @custom-variant dark (&:where(.dark, .dark *)); ``` WireKit ships its own `@custom-variant dark` inside `wirekit.css`, but that file arrives as a pre-compiled `` (via `@wirekitStyles`) and never reaches **your** Tailwind build — so your build still defaults `dark:` to `prefers-color-scheme`. This only affects `dark:` utilities you author yourself; WireKit components are unaffected (they don't use `dark:`). ### Styles not applying? If a component renders correct HTML but looks unstyled, the cause is your app's asset loading, not WireKit. Check, in order: 1. **`@source` line present** (Step 3) — Tailwind must scan WireKit's Blade templates, or the utility classes the components use are never generated. Verify with `grep @source resources/css/app.css`. 2. **`@wirekitStyles` in your layout** (Step 2) — it emits the `` to `wirekit.css`, which defines the `--*-wk-*` tokens. Without it, components render against undefined tokens. 3. **Fresh build** — Tailwind only generates classes it has scanned. After adding the `@source` line (or any new arbitrary-value token class), restart `npm run dev` or run `npm run build`; a dev server started before the change serves stale cached CSS. 4. **Stale published assets** — if you ran `php artisan vendor:publish --tag=wirekit-assets` once, `@wirekitStyles` keeps serving that published copy as long as its file timestamp is newer than the package `dist/`. Re-publish after a WireKit upgrade, or delete `public/vendor/wirekit/` to fall back to the always-current package copy. `php artisan wirekit:doctor` checks the first three automatically. ## Dark Mode (Optional) WireKit's tokens switch on a `.dark` class on ``. If your app offers dark mode, add one directive and one component rather than writing the plumbing: ```blade {{-- 1. BEFORE your stylesheet: applies the reader's stored theme before the first paint. Without it the page paints light and then turns dark in front of them. It is inline and synchronous for exactly that reason — moving it into a bundle brings the flash straight back. --}} @wirekitThemeScript {{-- 2. Your WireKit styles, as usual. --}} @wirekitStyles {{-- 3. The control, wherever it belongs in your chrome. --}} ``` Running a Content Security Policy? Pass your nonce: `@wirekitThemeScript($nonce)`. Full options, variants and the storage key: [theme controller](/components/theme-controller). ## Optional Dependencies WireKit's core has no front-end dependencies, but four components light up when you add a peer dependency. Install each **only if you use the component it powers** — every one degrades gracefully when its dependency is absent (the chart and map show an in-place advisory, the editor falls back to a plain textarea, the QR code is simply skipped). | Component | Peer dependency | Install | |-----------|-----------------|---------| | [``](/components/chart) | Chart.js *or* ApexCharts | `npm install chart.js` | | [``](/components/qr-code) | bacon/bacon-qr-code | `composer require bacon/bacon-qr-code` | | [``](/components/editor) | Tiptap | `npm install @tiptap/core @tiptap/starter-kit` | | [``](/components/map) | MapLibre GL *or* Leaflet | `npm install maplibre-gl` | `php artisan wirekit:doctor` lists these too — Chart.js by config + bacon-qr-code by package detection, and the editor/map engines as a reminder (they're browser globals a PHP command can't probe). ### Chart.js (for ``) ```bash npm install chart.js ``` ```javascript // resources/js/app.js // // 1. Pull Chart.js + the registerables bundle (the controllers, scales, // plugins, and elements that ship in the chart.js package). import { Chart, registerables } from 'chart.js'; // 2. Register everything globally so any chart type (bar, line, doughnut, // radar, …) works without per-call imports. Chart.register(...registerables); // 3. Expose Chart on window so WireKit's `wirekitChart` Alpine factory // can find the constructor at mount-time. The factory looks at // `window.Chart`; if it's not there, charts render the "Chart.js is // not loaded" placeholder. window.Chart = Chart; ``` Also set in `config/wirekit.php`: ```php 'charts' => [ 'library' => 'chartjs', ], ``` Chart.js dark mode works automatically — WireKit's Alpine component uses a `MutationObserver` to re-read CSS variables when the `.dark` class toggles. ### QR Code (for ``) ```bash composer require bacon/bacon-qr-code ``` No configuration needed — the component auto-detects the package. ### Rich-Text Editor (for ``) ```bash npm install @tiptap/core @tiptap/starter-kit ``` [``](/components/editor) is a thin Alpine adapter around a ProseMirror editor ([Tiptap](https://tiptap.dev) recommended). Expose a `window.wirekitEditor(config)` factory (the legacy `window.tiptapEditor` name still works as a deprecated alias) and the editor mounts the rich-text surface; without it, the editor degrades to a plain `