Install Preline UI with Qwik using Tailwind CSS

Install Preline UI with Tailwind CSS in Qwik projects, including JavaScript plugin setup, visible tasks, Qwik City navigation, and optional dependencies.

Installation

Please note that the plugin has been tested with the 1.12.1 version of the framework. The framework was installed using the standard npm create qwik@latest command.
If you are using your own project structure or a different version, pay attention to the file paths and features of your version!

Qwik quick setup

If Tailwind CSS is not set up yet, start with the official Qwik Tailwind CSS guide first.

Some components rely on third-party libraries. The setup below assumes full Preline UI usage with those dependencies preloaded. If you do not plan to use those components, you can remove the related libraries from your configuration.

Install Preline UI

Install preline with your preferred package manager.

Terminal

                          
                            npm install preline

Preline UI uses the Tailwind CSS Forms plugin across form components. Install it if you have not already: npm install -D @tailwindcss/forms

Include Preline CSS

Import Preline into projects_root_directory/src/global.css.

global.css

                          
                            @import "tailwindcss";

                            @import "preline/variants.css";
                            @source "../node_modules/preline/dist/*.js";

                            /* Optional Preline UI Datepicker Plugin */
                            /* @import "preline/datepicker-styles-utility.css"; */

                            /* Plugins */
                            /* @plugin "@tailwindcss/forms"; */

                            /* Preline Themes */
                            @import "preline/theme.css";

                            /* Optional Preline UI Datatable Plugin: DataTables.net renders its own
                              search/length/paging controls alongside Preline's own; hide the native
                              ones since they can't be disabled through DataTables options alone. */
                            /*
                            .dt-layout-row:has(.dt-search),
                            .dt-layout-row:has(.dt-length),
                            .dt-layout-row:has(.dt-paging) {
                              display: none !important;
                            }
                            */

See the Theme docs to learn more about Preline Themes.

Keep every @import statement grouped at the very top of the file, before @source or @plugin. CSS requires @import to precede all other statements (except @charset or an empty @layer name;), so an @import placed after @source/@plugin is invalid and gets dropped. Depending on your Tailwind CSS integration this either fails the build with an explicit @import must precede all other statements error, or, with the Vite plugin integration, fails silently with no error at all, so Preline's theme/variant CSS simply never reaches the compiled output.

Add type definitions for Preline

Create a global.d.ts file for the shared window typings, for example projects_root_directory/global.d.ts. Add typings here for any optional third-party globals too (jQuery, lodash, etc.) as you wire in the plugins that need them; see Optional dependencies.

global.d.ts

                          
                            declare global {
                              interface Window {
                                HSStaticMethods?: typeof import("preline/non-auto").HSStaticMethods;
                              }
                            }

                            export {};

Create a Preline init helper

Create a small client-only module, for example projects_root_directory/src/lib/preline.ts, that lazily imports preline/non-auto and caches the resolved HSStaticMethods reference. The next step calls this on every client-side route change, so caching matters: re-importing an already-loaded module resolves from the module cache, but it is still asynchronous every time, which is enough for a click right after navigation to land before Preline has attached its listeners.
type HSStaticMethodsType = typeof import("preline/non-auto").HSStaticMethods; let hsStaticMethods: HSStaticMethodsType | null = null; let setupPromise: Promise<void> | null = null; async function setup() { // Load optional plugin dependencies here, before the next line. // See "Optional dependencies" in the Qwik framework guide. hsStaticMethods = (await import("preline/non-auto")).HSStaticMethods; } export function initPreline() { if (hsStaticMethods) { hsStaticMethods.autoInit(); return; } if (!setupPromise) { setupPromise = setup(); } setupPromise.then(() => { hsStaticMethods!.autoInit(); }); }
src/lib/preline.ts
```
                          
                        
```
This module never reads window/document at the top level, so importing it has no effect during server rendering: the dynamic import() inside setup() only actually resolves once initPreline() is first called from the browser, in the next step. Avoid loading Preline (or its optional dependencies) via a raw, unconditional <script> tag in the root layout, since that ships the full bundle inline in every page's HTML regardless of whether that route uses any Preline component, which works against Qwik's resumability model instead of with it.
Reinitialize on route changes

Call the helper from projects_root_directory/src/routes/layout.tsx so Preline scans the DOM once on load, and again after every Qwik City client-side navigation.
import { component$, Slot, useSignal, useVisibleTask$ } from "@builder.io/qwik"; import { initPreline } from "../lib/preline"; export default component$(() => { const contentRef = useSignal<HTMLDivElement>(); useVisibleTask$( ({ cleanup }) => { const target = contentRef.value; if (!target) return; let debounce: ReturnType<typeof setTimeout> | undefined; const observer = new MutationObserver(() => { clearTimeout(debounce); debounce = setTimeout(initPreline, 0); }); observer.observe(target, { childList: true, subtree: true }); cleanup(() => { clearTimeout(debounce); observer.disconnect(); }); initPreline(); }, { strategy: "document-ready" }, ); return ( <div ref={contentRef}> <Slot /> </div> ); });
layout.tsx
```
                          
                        
```
Two details here matter and are easy to get wrong: tracking useLocation().url.pathname with track() looks like the obvious way to trigger a rescan, but that signal can update in Qwik's reactivity graph before Qwik City finishes patching the <Slot /> with the new route's markup, so autoInit() then scans a DOM that does not have the new route's elements yet, and nothing retriggers it afterward since the signal only changes once per navigation. A MutationObserver on the element <Slot /> renders into reacts to the actual DOM change instead, regardless of timing. Second, use { strategy: "document-ready" } rather than the default intersection-observer strategy. The default gates the task's first run behind the tracked element's reported viewport-intersection state, which is unnecessary for something that should simply run once the page is interactive, and has been observed to never fire at all in some real conditions (see the Qwik framework guide).

Optional Preline UI styles

Preline UI ships with a small set of opinionated base styles. If you want them in your project, add them to your CSS file. These defaults used to come bundled with Tailwind CSS v3, so they are still available as an optional layer in Preline UI.

CSS

                        
                          /* Adds pointer cursor to buttons */
                          @layer base {
                            button:not(:disabled),
                            [role="button"]:not(:disabled) {
                              cursor: pointer;
                            }
                          }

                          /* Defaults hover styles on all devices */
                          @custom-variant hover (&:hover);