FlyOnUI Condensed and LLM-Friendly Documentation

flyonui.md

FlyonUI Developer Guide

This is a summarized and simplified on-page guide based on the FlyOnUI documentation, intended for use as context for LLM-assisted coding. It was created with a summarization workflow created in n8n and then summarized with Genimi 2.0 Flash, and the final document restructured and reformatted using Gemini 2.5-pro.

1. Overview

What is FlyonUI?

FlyonUI is an open-source Tailwind CSS component library. It provides semantic classes and JavaScript-enhanced components for building user interfaces.

Core Technologies

• Tailwind CSS: A utility-first CSS framework.
• daisyUI (Conceptual Basis): Provides semantic class names for Tailwind CSS components.
• Preline (Conceptual Basis): Offers JavaScript headless and unstyled Tailwind plugins.

Functionality Summary

FlyonUI integrates as an NPM development dependency and is added as a plugin to your Tailwind CSS configuration. It offers CSS components with semantic class names and headless JavaScript plugins for dynamic features like accordions, dropdowns, and modals. Components can be used for UI creation, with Tailwind CSS utilities for fine-tuning. It supports responsive design and RTL languages.

2. Getting Started

Installation

npm install flyonui

CSS Configuration

Full Library (app.css):

@import "tailwindcss";
@plugin "flyonui";
@import "./node_modules/flyonui/variants.css"; /* Required for FlyonUI JS components */
@source "./node_modules/flyonui/dist/index.js"; /* Required for FlyonUI JS components */

Single CSS Component Import: To include only specific CSS components (e.g., badge, dropdown, timeline), configure the plugin:

@plugin "flyonui" { include: badge, dropdown, timeline;}

(Note: The syntax @plugin "flyonui" { ... } is PHP-like but used here to denote CSS configuration block as per the source document.)

Single JS Component CSS Import (Example: Accordion): If importing a single JS component, its specific CSS variants and JS source might be needed:

/* In your main.css or app.css */
@plugin "flyonui" { include: accordion;} /* Ensure CSS for accordion is included */
@import "./node_modules/flyonui/src/js/plugins/accordion/variants.css"; /* Specific variants for accordion JS */
@source "./node_modules/flyonui/dist/accordion.js"; /* JS source for accordion */

JavaScript Integration

Full Library (HTML):

<script src="../node_modules/flyonui/flyonui.js"></script>

Single Component (HTML, Example: Accordion):

<script src="../node_modules/flyonui/dist/accordion.js"></script>

Icon Setup

FlyonUI uses Tabler icons via Iconify.

1. Install Plugins:

   npm i -D @iconify/tailwind4 @iconify-json/tabler

2. CSS Integration:

   @plugin "@iconify/tailwind4";

3. HTML Usage:

   <span class="icon-[tabler--upload]"></span>

   To use other Iconify icon sets, install the relevant @iconify-json/* package (or @iconify/json for all) and use the format icon-[icon-set--icon-name]. Size can be controlled with Tailwind's size-[number] (e.g., size-10).

Bundling (e.g., Webpack, Parcel)

Import Full FlyonUI JavaScript (e.g., app-bundle.js):

import "flyonui/flyonui";

Import Single Component (e.g., app-bundle.js for Accordion):

import "flyonui/dist/accordion";

Include Bundled JS in HTML:

<script src="../path-to-your-bundle/flyonui.js"></script> <!-- Or your main bundle name -->

3. Configuration

FlyonUI is configured within your CSS file using the @plugin "flyonui" { ... } block.

Default Config:

@plugin "flyonui" {
  themes: light --default, dark --prefersdark;
  root: ":root";
  include: ; /* Empty by default, includes all */
  exclude: ; /* Empty by default, excludes none */
  logs: true;
}

Configuration Options

• themes: (string or comma-separated list, or false or all)

  • Default: light --default, dark --prefersdark
  • Specifies themes to enable.
  • false: Disables all themes (except any implicitly default ones if not overridden).
  • all: Enables all built-in themes.
  • --default: Marks a theme as the default for light mode.
  • --prefersdark: Sets a theme as the default when prefers-color-scheme: dark is active.
  • Example: themes: soft --default, luxury --prefersdark, gourmet, corporate;

• root: (string)

  • Default: :root
  • CSS selector where FlyonUI's CSS variables are applied.
  • Example: root: "#app";

• include: (comma-separated list)

  • Default: (empty)
  • Includes only specified components. All others are excluded.
  • Example: include: badge, dropdown, timeline;

• exclude: (comma-separated list)

  • Default: (empty)
  • Excludes specified components. All others are included. Also used to opt-out of base styles (see Base Styles).
  • Example: exclude: radio, chat, timeline;

• logs: (boolean)

  • Default: true
  • Enables/disables console logs from FlyonUI.
  • Example: logs: false;

4. Core Styling Concepts

Component Classes

Pre-defined styles for HTML elements.

<button class="btn">Button</button>

Customize with FlyonUI utility classes or Tailwind CSS utilities:

<button class="btn btn-primary">Button</button>
<button class="btn rounded-full">Button</button>

Or using @apply in CSS:

.btn { @apply rounded-full; }

Modifier Classes

Allow dynamic component changes based on events or states. Syntax: modifier:property. Example (Collapse component):

<button type="button" class="collapse-toggle btn btn-primary" data-collapse="#myCollapse">
    <span class="collapse-open:hidden">Collapsed</span>
    <span class="collapse-open:block hidden">Collapse</span>
    <span class="icon-[tabler--chevron-down] collapse-open:rotate-180"></span>
</button>
<div id="myCollapse" class="collapse hidden">...</div>

Utility Classes & CSS Variables

Semantic Colors

FlyonUI uses semantic color utility classes (e.g., bg-primary, text-info) that adapt to theme changes via CSS variables.

Available Color Options & Variables: (CSS Variable format: var(--color-{name}), Utility class examples: bg-{name}, text-{name-content})

• Primary: Main brand color. (--color-primary, --color-primary-content)
• Secondary: Complementary accent. (--color-secondary, --color-secondary-content)
• Accent: For highlighting. (--color-accent, --color-accent-content)
• Neutral: For less prominent elements. (--color-neutral, --color-neutral-content)
• Base 100/200/300: Surface colors (lightest to darker). (--color-base-100, --color-base-200, --color-base-300)
• Base Content: Foreground for base colors. (--color-base-content)
• Info: Informational messages. (--color-info, --color-info-content)
• Success: Positive states. (--color-success, --color-success-content)
• Warning: Potential issues. (--color-warning, --color-warning-content)
• Error: Error messages. (--color-error, --color-error-content)

Applying Colors:

<span class="badge badge-primary">Badge</span>
<input type="radio" class="radio radio-primary" />

Utility classes available for: bg, text, border, from, via, to (gradients), ring, fill, stroke, shadow, outline, divide, accent, caret, decoration, placeholder, ring-offset. Example: bg-primary/50 (background with 50% opacity).

Extended Border Radius Utilities

Dynamically adjust based on the active theme.

• rounded-box: For large components (cards, modals). Variable: var(--radius-box)
• rounded-field: For medium components (buttons, inputs). Variable: var(--radius-field)
• rounded-selector: For small components (checkboxes, badges). Variable: var(--radius-selector) Tailwind border-radius utilities like rounded-r-box also work.

Theme-Specific CSS Variables

Customize these per theme:

• --color-{name} and --color-{name}-content (as listed above)
• --radius-selector, --radius-field, --radius-box (border radiuses)
• --size-selector, --size-field (base sizes for small/medium components)
• --border (border width for all components)
• --depth (binary: 0 or 1, adds depth effect)
• --noise (binary: 0 or 1, adds noise effect to backgrounds)

Component-Specific CSS Variables

Selected examples:

• Alert: --alert-color
• Button: --btn-color, --btn-fg, --btn-shadow, --btn-noise, --btn-p, --size
• Card: --card-p, --card-border, --card-shadow
• Checkbox/Radio/Switch: --input-color, --size
• Input/Select/Textarea: --input-color, --size
• Radial Progress: --value, --size, --thickness
• Range: --range-color (thumb color), --range-thumb-size
• Glass Effect: --glass-blur, --glass-opacity, etc.
• Join: --join-ss, --join-se, etc. (border radius for start/end items)

Custom JS Component Variants

Apply Tailwind utility classes based on a component's JS-driven state. Examples:

• dropdown-open:{tw-utility-class}
• accordion-item-active:{tw-utility-class}
• collapse-open:{tw-utility-class}
• overlay-open:{tw-utility-class}
• selected:{tw-utility-class} (e.g., for custom selects)
• password-active:{tw-utility-class} (for toggle password visibility)
• stepper-active:{tw-utility-class}

Glass Effect

Apply the glass class for a frosted-glass appearance.

<div class="glass">Glass Content</div>

Base Styles

FlyonUI applies essential base styles. Opt-out using exclude in the config (e.g., exclude: scrollbar, rootcolor;).

• properties.css: Defines variable types (e.g., --radialprogress).
• rootcolor.css: Defines background-color (base-100) and text-color (base-content) for :root and [data-theme].
• scrollbar.css: Customizes scrollbar appearance.
• svg.css: Includes small inline SVG assets (noise filters, chat/tooltip tails).

RTL Support

FlyonUI components support RTL. Enable by adding dir="rtl" to the <html> tag. CSS logical properties (e.g., ms-0 instead of ml-0) are used. Use rtl: variants for custom RTL styling (e.g., rtl:mr-2.5).

5. Theming

Manage themes within the @plugin "flyonui" { themes: ... } block in your CSS.

@plugin "flyonui" {
  themes: light --default, dark --prefersdark, gourmet;
}

• --default: Default theme for light mode.
• --prefersdark: Applies if prefers-color-scheme: dark.

Applying a Theme in HTML:

<html data-theme="gourmet"></html>

If no data-theme, system preference is used.

Built-in Themes: light, dark, black, corporate, ghibli, gourmet, luxury, mintlify, shadcn, slack, soft, valorant.

Font Family: light and dark themes use default font-sans. Other themes may require additional font imports in <head> (refer to original "Themes - Developer Reference" for specific font links if needed, but generally these would be user-managed).

Theme Management:

• Activate All: themes: all;
• Remove Unused: List only desired themes in the config.
• Disable All (except defaults): themes: false;
• Disable Dark Theme: themes: light --default;

Theme Sections: Apply data-theme to specific elements.

<html data-theme="dark">
  <div data-theme="light">This div uses light theme.</div>
</html>

Adding a Custom Theme: Use the @plugin "flyonui/theme" { ... } block.

@plugin "flyonui/theme" {
  name: "mycustomtheme";
  default: true;          /* Optional: Set as default */
  prefersdark: false;     /* Optional: Set for dark mode preference */
  color-scheme: light;    /* Optional: Browser UI color scheme hint */

  /* Required Theme Variables */
  --color-base-100: oklch(98% 0.01 300); /* Example value */
  --color-base-content: oklch(30% 0.07 300); /* Example value */
  --color-primary: oklch(70% 0.18 300); /* Example value */
  --color-primary-content: oklch(95% 0.03 300); /* Example value */
  /* ... other required --color variables (secondary, accent, neutral, info, success, warning, error and their -content) */

  /* Optional Theme Variables */
  --radius-selector: 1rem;
  --radius-field: 0.25rem;
  --radius-box: 0.5rem;
  --size-selector: 0.25rem;
  --size-field: 0.25rem;
  --border: 1px;
  --depth: 1; /* 0 or 1 */
  --noise: 0; /* 0 or 1 */
}

Custom CSS for a Theme:

[data-theme="light"] .my-btn {
  background-color: #1EA1F1;
}

Customize Existing Theme: Override variables within the @plugin "flyonui/theme" { name: "theme-to-customize"; ... } block.

@plugin "flyonui/theme" {
  name: "light"; /* Target the existing 'light' theme */
  default: true; /* Keep or re-assign as default */
  --color-primary: blue;
  --color-secondary: teal;
}

Tailwind's dark: Selector with Themes: To apply Tailwind's dark: prefix to specific themes:

@plugin "flyonui" {
  themes: soft --default, luxury --prefersdark;
}
/* Apply dark variant styles when luxury theme is active OR system dark mode is on */
@custom-variant dark (&:where([data-theme=luxury], [data-theme=luxury] *), &:where([data-theme=dark], [data-theme=dark] *));

<div class="p-10 dark:p-20">
  <!-- Padding is 10 on soft/light, 20 on luxury/dark -->
</div>

6. Components

(This section will list components with condensed information: key classes, a primary usage example, and notes on JS behavior if applicable. For brevity, only a few representative components will be fully detailed here. The pattern should be followed for others.)

6.1 Content & Display

Accordion

Reveals content by toggling collapse/expand states. Requires FlyonUI JS.

Key Classes:

• accordion: Main container.
• accordion-item: Single item.
• accordion-toggle: Button to toggle.
• accordion-content: Collapsible content area.
• active: State class for active item.
• accordion-item-active:{util}: Variant for active item styling.
• Styles: accordion-bordered, accordion-shadow.
• Tree View: accordion-treeview-root, accordion-heading, accordion-selectable.

Basic Usage:

<div class="accordion divide-neutral/20 divide-y">
  <div class="accordion-item active" id="payment-basic">
    <button class="accordion-toggle ..." aria-controls="payment-basic-collapse" data-accordion-toggle="#payment-basic-collapse">
      <span class="icon-[tabler--plus] accordion-item-active:hidden ..."></span>
      <span class="icon-[tabler--minus] accordion-item-active:block hidden ..."></span>
      When is payment taken?
    </button>
    <div id="payment-basic-collapse" class="accordion-content w-full overflow-hidden transition-[height] duration-300">
      <p>Payment is taken during checkout.</p>
    </div>
  </div>
</div>

JS Behavior:

• Options: data-accordion-always-open (boolean), [--keep-one-open:*] (boolean).
• Methods: show(), hide(), destroy(). Static: HSAccordion.getInstance(), HSAccordion.show(), HSAccordion.hide().
• Events: beforeOpen, beforeClose.

Alert

Displays notifications.

Key Classes:

• alert: Main container.
• Styles: alert-soft, alert-outline.
• Colors: alert-{semantic-color} (e.g., alert-primary, alert-success).

Basic Usage:

<div class="alert alert-success" role="alert">
  Your transaction was successful!
</div>
<div class="alert alert-soft alert-warning flex items-center gap-4" role="alert">
  <span class="icon-[tabler--alert-triangle] shrink-0 size-6"></span>
  <p>Warning: Enable two-factor authentication.</p>
</div>

Dismissible alerts use data-remove-element="#alertId" on a close button.

Avatar

Displays user profile pictures or placeholders.

Key Classes:

• avatar: Main container.
• avatar-group: For grouping avatars.
• avatar-placeholder: For letter/icon placeholders.
• Status indicators: avatar-online-top, avatar-online-bottom, etc. (FlyonUI 2: previously online-top).

Basic Usage:

<!-- Image Avatar -->
<div class="avatar">
  <div class="size-12 rounded-full">
    <img src="path/to/avatar.png" alt="avatar" />
  </div>
</div>

<!-- Placeholder Avatar (FlyonUI 2) -->
<div class="avatar avatar-placeholder">
  <div class="bg-neutral text-neutral-content w-10 rounded-full">
    <span class="text-md uppercase">JD</span>
  </div>
</div>

<!-- Avatar Group -->
<div class="avatar-group -space-x-4">
  <div class="avatar">...</div>
  <div class="avatar">...</div>
</div>

... (Other Content & Display components follow a similar condensed pattern) ...

6.2 Navigation

Navbar

Navigation bar for top-of-page links.

Key Classes:

• navbar: Main container.
• navbar-start, navbar-center, navbar-end: For layout sections.

Basic Usage (Responsive):

<nav class="navbar rounded-box shadow-sm">
  <div class="navbar-start">
    <a class="link text-xl font-bold no-underline" href="#">FlyonUI</a>
  </div>
  <div class="navbar-center hidden lg:flex">
    <ul class="menu menu-horizontal p-0">
      <li><a href="#">Home</a></li>
      <li><a href="#">About</a></li>
    </ul>
  </div>
  <div class="navbar-end">
    <div class="dropdown dropdown-end lg:hidden">
      <button class="btn btn-square btn-ghost" aria-label="Open menu">
        <span class="icon-[tabler--menu-2] size-5"></span>
      </button>
      <ul class="menu dropdown-content mt-3 z-[1] p-2 shadow bg-base-100 rounded-box w-52">
        <li><a href="#">Home</a></li>
        <li><a href="#">About</a></li>
      </ul>
    </div>
    <button class="btn btn-primary hidden lg:inline-flex">Get Started</button>
  </div>
</nav>

Uses Collapse JS for mobile menu toggling.

... (Other Navigation components) ...

6.3 Forms

Input

Standard text input fields.

Key Classes:

• input: Base class.
• input-floating: Wrapper for floating labels.
• input-floating-label: The floating label itself.
• label-text, helper-text.
• Sizes: input-xs, input-sm, input-md, input-lg, input-xl.
• States: is-valid, is-invalid.

Basic Usage:

<div>
  <label class="label-text" for="nameInput">Name</label>
  <input type="text" id="nameInput" class="input max-w-sm" placeholder="John Doe" />
  <span class="helper-text">Enter your full name.</span>
</div>

Floating Label Usage (FlyonUI 2):

<div class="input-floating w-96">
  <input type="text" placeholder="John Doe" class="input" id="floatingInput" />
  <label class="input-floating-label" for="floatingInput">Full Name</label>
</div>

Input groups are created by wrapping elements within an outer div with the input class.

... (Other Form components) ...

6.4 Advanced Forms

Advanced Select

Enhanced select boxes with search and tagging. Requires FlyonUI JS.

Key Classes:

• advance-select-toggle: Toggle button style.
• advance-select-menu: Dropdown menu style.
• advance-select-option: Option item style.
• advance-select-tag: Wrapper for tags mode.
• State: select-active. Variants: select-opened:{util}, selected:{util}.
• Sizes: advance-select-{xs|sm|md|lg|xl} (applied to toggle).

Basic Usage:

<div class="max-w-sm">
  <select
    data-select='{
      "placeholder": "Select option...",
      "toggleTag": "<button type=\"button\" aria-expanded=\"false\"></button>",
      "toggleClasses": "advance-select-toggle advance-select-md ...",
      "dropdownClasses": "advance-select-menu ...",
      "optionClasses": "advance-select-option selected:select-active",
      "optionTemplate": "<div class=\"flex justify-between items-center w-full\"><span data-title></span><span class=\"icon-[tabler--check] ... selected:block\"></span></div>",
      "extraMarkup": "<span class=\"icon-[tabler--caret-up-down] ...\"></span>"
    }'
    class="hidden"
  >
    <option value="">Choose</option>
    <option value="name">Full Name</option>
    </select>
</div>

JS Behavior:

• Options via data-select JSON: placeholder, hasSearch, searchLimit, minSearchLength, mode: "tags", toggleCountText, etc.
• Methods: setValue(), getValue(), destroy(). Static: HSSelect.getInstance().
• Events: on:change.

... (Other Advanced Form components) ...

6.5 Overlays

Modal

Dialog box that appears on top of page content. Requires FlyonUI JS.

Key Classes:

• overlay: JS target, main backdrop container.
• modal: Styles the overlay as a modal.
• modal-dialog: Content container within the modal.
• modal-content, modal-header, modal-title, modal-body, modal-footer.
• Sizes: modal-dialog-sm, modal-dialog-md (default), modal-dialog-lg, modal-dialog-xl.
• Placement: modal-top-start, modal-middle, etc.
• Variants: overlay-open:{util}, overlay-backdrop-open:{util}.

Basic Usage:

<button type="button" class="btn btn-primary" data-overlay="#basic-modal">Open modal</button>

<div id="basic-modal" class="overlay modal hidden overlay-open:opacity-100 overlay-open:duration-500" role="dialog" tabindex="-1">
  <div class="modal-dialog overlay-open:opacity-100 overlay-open:duration-500"> <!-- Add overlay-open animation here too -->
    <div class="modal-content">
      <div class="modal-header">
        <h3 class="modal-title">Modal Title</h3>
        <button type="button" class="btn btn-text btn-circle btn-sm ..." data-overlay="#basic-modal" aria-label="Close">
          <span class="icon-[tabler--x] size-4"></span>
        </button>
      </div>
      <div class="modal-body">...</div>
      <div class="modal-footer">
        <button type="button" class="btn btn-soft btn-secondary" data-overlay="#basic-modal">Close</button>
        <button type="button" class="btn btn-primary">Save</button>
      </div>
    </div>
  </div>
</div>

JS Behavior:

• Options via data-overlay-options or CSS custom properties: isClosePrev (for stacked modals), [--has-autofocus:false], [--body-scroll:true], [--auto-hide:{ms}], [--overlay-backdrop:static|false].
• Methods: open(), close(), destroy(). Static: HSOverlay.getInstance(), HSOverlay.open(), HSOverlay.close().
• Events: on:open, on:close.

... (Other Overlay components) ...

7. JavaScript API (General)

HSStaticMethods.autoInit()

Reinitializes dynamically added UI components. Declaration: window.HSStaticMethods.autoInit(componentNames?: string[])

• If componentNames (e.g., ["carousel", "dropdown"]) is omitted, all components are reinitialized.

Example (AJAX loaded elements): After loading and populating dynamic content (e.g., options for a select):

// ... (AJAX logic to populate selectElement) ...
window.HSStaticMethods.autoInit(["select"]); // Reinitialize only the select component

TypeScript Declaration

import { IStaticMethods } from "flyonui/flyonui"; // Path may vary based on actual export
declare global {
  interface Window {
    HSStaticMethods: IStaticMethods;
  }
}
window.HSStaticMethods.autoInit();

Preventing Auto-Initialization

Add the --prevent-on-load-init CSS class to an element to stop its automatic JS initialization. Initialize manually:

<select data-select='{...}' class="--prevent-on-load-init hidden">...</select>

document.addEventListener("DOMContentLoaded", () => {
  document.querySelectorAll("[data-select].--prevent-on-load-init").forEach(el => {
    new HSSelect(el); // Assuming HSSelect is the constructor for the select component
  });
});

8. FlyonUI 2 Upgrade Notes (Key Changes)

Tailwind CSS Prerequisite

FlyonUI 2 requires an upgrade of your Tailwind CSS setup. Typically involves removing FlyonUI from tailwind.config.js plugins and running npx @tailwindcss/upgrade.

Core FlyonUI Upgrade

1. Install Latest: npm i -D flyonui@latest
2. CSS Import: Update your main CSS:

   @import "tailwindcss";
   @plugin "flyonui"; /* Configure themes directly here */
   @import "./node_modules/flyonui/variants.css";

   Example with theme config:

   @plugin "flyonui" { themes: light --default, dark --prefersdark, soft; }

3. JavaScript: Ensure flyonui.js is included:

   <script src="../node_modules/flyonui/flyonui.js"></script>

Notable Component Changes (Examples from v2 Upgrade Guide)

• Content Block - Custom Scrollbar: Removed vertical-scrollbar, horizontal-scrollbar, rounded-scrollbar. Styles are now global via scrollbar.css.
• KBD (Keyboard): Added kbd-md (default), kbd-xl. kbd height adjusted.
• Alert/Badge/Button: *-neutral style removed; neutral is now the default style. New *-md (default) and *-xl sizes added.
• Avatar: Class renames (breaking): placeholder -> avatar-placeholder, online-top -> avatar-online-top, etc.
• Card: card-compact removed (use card-sm). Added card-border and sizes card-xs to card-xl.
• Input: input-group removed. Grouping achieved by wrapping inputs with an outer div.input. input-filled removed. label and label-text-alt for helper text changed to label-text and span.helper-text. Floating label structure updated.
• Menu: State classes renamed (breaking): disabled -> menu-disabled, focus -> menu-focus, active -> menu-active.
• Dropdown: active -> dropdown-active, disabled -> dropdown-disabled. Popper.js replaced by Floating UI.
• Modal: Backdrop color changed. Use overlay-open:duration-500 with modal and modal-dialog for transition.
• Artboard/Phone (Mockups): artboard and phone-* classes removed. Use Tailwind w-* and h-*. Phone mockup parts renamed: camera -> mockup-phone-camera, display -> mockup-phone-display.
• Table: .hover -> .row-hover, .active -> .row-active.
• Third-Party Color Syntax: In JS for charts (ApexCharts, Datamaps), oklch(var(--bc) / 0.4) changed to color-mix(in oklab, var(--color-base-content) 40%, transparent).

9. License

FlyonUI is free for personal and commercial use under the MIT License. It incorporates open-source software:

• Preline: MIT License & Preline UI Fair Use License.
• daisyUI: MIT License. Copyright (c) 2024 ThemeSelection (for FlyonUI). Refer to the original license file for full details.