DOCSEARCHbyAlgolia
Submit Docs

Preline UI Documentation

repository·main·Indexed 27 days ago

https://github.com/htmlstreamofficial/preline

An open-source set of prebuilt UI components, reusable blocks, templates, and headless plugins based on the utility-first Tailwind CSS framework. Version 4.2.0 includes detailed guides on installation, JavaScript implementation, and specific plugins such as Accordion and Carousel, as well as information on Preline Pro premium components and Agent Skills for AI coding tools.

Tokens
70.4K
Snippets
208
Records
320
Agent score
91%

What's inside Preline UI

  1. Understand Preline Theme Semantic Tokens

    main

    Preline themes utilize CSS custom properties (variables) as semantic tokens to ensure consistent styling across components.

    Key implementation details:

    • Tokens are defined under :root for light mode and .dark for dark mode.
    • They are mapped to Tailwind utilities via @theme inline in the base theme.
    • Important: When generating custom themes, you should only override the token values. Do not redefine the Tailwind mappings themselves.

  2. Access Preline Pro premium components

    main
    Preline Pro is a paid extension of the free library designed for commercial applications. It provides access to premium Tailwind CSS blocks, sections, and full templates for various use cases including admin dashboards, SaaS, ecommerce, and marketing.

  3. Initialize Strong Password via Bundler

    main

    When using a bundler like Vite or Webpack, you can choose between automatic or manual initialization:

    1. Auto-init: Import @preline/strong-password to automatically scan the DOM and initialize matching elements.
    2. Manual init: Import @preline/strong-password/non-auto to control exactly when initialization occurs using autoInit() or by creating specific instances.
    // Auto-init mode
import "@preline/strong-password";

// Manual entry mode
import HSStrongPassword from "@preline/strong-password/non-auto";

// Initialize all matching elements
HSStrongPassword.autoInit();

// Or initialize a specific element manually
const el = document.querySelector("#strong-password");
if (el) new HSStrongPassword(el);

  4. Install Preline Agent Skills for AI Coding Tools

    main

    Preline UI provides 'Agent Skills' to help agentic coding tools (like Cursor, Claude Code, and Gemini CLI) automate theme generation and UI workflows. You can install these skills via the CLI.

    npx skills add htmlstreamofficial/preline

  5. Implement Scroll Nav HTML structure

    main

    To use Scroll Nav, you must follow a specific HTML structure with required data attributes and classes:

    • data-hs-scroll-nav: Required on the container element.
    • hs-scroll-nav-prev: Required class on the previous button.
    • hs-scroll-nav-next: Required class on the next button.
    • hs-scroll-nav-body: Required class on the scrollable navigation container.

    Navigation items should be placed inside the hs-scroll-nav-body container.

    <div data-hs-scroll-nav class="relative px-6">
  <button type="button" class="hs-scroll-nav-prev">Previous</button>

  <nav class="hs-scroll-nav-body flex flex-nowrap overflow-x-auto snap-x snap-mandatory">
    <a class="snap-start" href="#">Electronics</a>
    <a class="snap-start" href="#">Clothing</a>
    <!-- ... other items ... -->
  </nav>

  <button type="button" class="hs-scroll-nav-next">Next</button>
</div>

  6. Implement custom neutral (gray) palettes with bell curve chroma

    main

    Custom gray palettes should harmonize with the primary color and use a bell curve chroma pattern. This ensures light backgrounds look clean and dark backgrounds look sophisticated rather than muddy.

    Chroma Distribution Pattern

    Chroma should peak at mid-tones (400-600) and be very low at both extremes (50 and 950).

    ShadeRecommended ChromaPurpose
    9500.003Nearly pure dark, avoids muddiness
    9000.005Very low chroma
    8000.008Just a hint of tint
    5000.020PEAK chroma (mid-tones)
    500.002Almost neutral, clean light background

    Implementation Example

    Define the palette in the @theme block and reference it via var() in your theme selectors.

    @theme theme-<name> inline {
  /* Custom neutral palette */
  --color-<name>-50:  oklch(98%   0.002 <hue>);
  --color-<name>-100: oklch(95.5% 0.004 <hue>);
  /* ... full 50-950 scale ... */
  --color-<name>-950: oklch(20.1% 0.003 <hue>);
}

[data-theme="theme-<name>"] {
  --background: var(--color-<name>-50);
  --background-1: var(--color-<name>-100);
}

[data-theme="theme-<name>"].dark {
  --background: var(--color-<name>-950);
  --background-1: var(--color-<name>-900);
}
    @theme theme-<name> inline {
  /* Custom neutral palette for this theme */
  --color-<name>-50: oklch(98% 0.003 88);
  --color-<name>-100: oklch(95.5% 0.005 88);
  /* ... full 50-950 scale ... */
}

[data-theme="theme-<name>"] {
  --background: var(--color-<name>-50);
  --background-1: var(--color-<name>-100);
  /* ... */
}

[data-theme="theme-<name>"].dark {
  --background: var(--color-<name>-950);
  --background-1: var(--color-<name>-900);
  /* ... */
}

  8. Include Preline JavaScript in HTML

    main

    To enable interactive components (like dropdowns, modals, and tabs), you must include the Preline JavaScript file in your HTML document, ideally just before the closing </body> tag.

    <script src="./node_modules/preline/dist/preline.js"></script>

  9. Initialize Advanced Datepicker via Bundler

    main

    When using a bundler like Vite or Webpack, you can initialize the datepicker in two ways:

    1. Auto-initialization: Import @preline/datepicker to automatically scan the DOM and initialize matching elements.
    2. Manual initialization: Import HSDatepicker from @preline/datepicker/non-auto to control exactly when initialization occurs using autoInit() or by creating new instances manually.
    // Auto-init mode
import "@preline/datepicker";

// Manual mode
import HSDatepicker from "@preline/datepicker/non-auto";

// Initialize all matching elements
HSDatepicker.autoInit();

// Or initialize a specific element
const el = document.querySelector("#datepicker");
if (el) new HSDatepicker(el);

  10. Use the Preline Theme Generator

    main

    The Preline Theme Generator is used to generate, preview, save, or validate Preline theme CSS. It allows you to create new themes based on brand colors, moods (e.g., 'sunset' or 'cyberpunk'), or specific requirements like matching light and dark modes.

    Capabilities:

    • Generate light and dark theme CSS.
    • Match specific brand colors (e.g., #2F6BFF).
    • Preview theme output without writing files.
    • Review and fix generated theme tokens.

    Execution Entry Point: All CSS generation must be performed using the bundled local script: scripts/run-theme-generator.js.

  11. Implement Tabs basic HTML structure

    main

    To create a functional tabs component, follow this structure. Ensure all ARIA roles and data attributes are present.

    Requirements:

    • role="tablist" on the container.
    • role="tab" on each button.
    • role="tabpanel" on each content section.
    • data-hs-tab="#selector" on each button, pointing to the panel's ID.
    • Unique id attributes for buttons and panels.
    • aria-selected, aria-controls, and aria-labelledby for accessibility.

    Initial State:

    • Active Tab: Add the active class to the button and set aria-selected="true".
    • Inactive Tab: Add the hidden class to the panel and set aria-selected="false".
    <nav class="flex gap-x-2" aria-label="Tabs" role="tablist">
  <button type="button" class="active" id="hs-unstyled-tabs-item-first" aria-selected="true" data-hs-tab="#hs-unstyled-tabs-first" aria-controls="hs-unstyled-tabs-first" role="tab">
    Tab 1
  </button>
  <button type="button" id="hs-unstyled-tabs-item-second" aria-selected="false" data-hs-tab="#hs-unstyled-tabs-second" aria-controls="hs-unstyled-tabs-second" role="tab">
    Tab 2
  </button>
  <button type="button" id="hs-unstyled-tabs-item-third" aria-selected="false" data-hs-tab="#hs-unstyled-tabs-third" aria-controls="hs-unstyled-tabs-third" role="tab">
    Tab 3
  </button>
</nav>

<div class="mt-3">
  <div id="hs-unstyled-tabs-first" role="tabpanel" aria-labelledby="hs-unstyled-tabs-item-first">
    This is the <em>first</em> item's tab body.
  </div>
  <div id="hs-unstyled-tabs-second" class="hidden" role="tabpanel" aria-labelledby="hs-unstyled-tabs-item-second">
    This is the <em>second</em> item's tab body.
  </div>
  <div id="hs-unstyled-tabs-third" class="hidden" role="tabpanel" aria-labelledby="hs-unstyled-tabs-item-third">
    This is the <em>third</em> item's tab body.
  </div>
</div>

  12. Initialize Advanced Select via CDN

    main

    For non-bundler environments, include the JavaScript files at the end of your <body> tag. If using advanced positioning, load the Floating UI UMD bundle first to expose the FloatingUIDOM global.

    <!-- Optional: required for dropdownScope: "window", dropdownPlacement, dropdownAutoPlacement -->
<script src="https://cdn.jsdelivr.net/npm/@floating-ui/dom@latest/dist/floating-ui.dom.umd.min.js"></script>
<script src="./node_modules/@preline/select/index.js"></script>