The utility-first CSS
framework for the browser.
Jetflow is a browser-native, atomic CSS framework. Drop in a single <script> tag, write
utility classes in your HTML, and your styles are generated in real time — no build step, no configuration
required to get started.
DISCLAIMER: Jetflow is an independent open-source project
and is not affiliated with any otherJetflow-branded products.
What's new in v1.0.1?
Jetflow v1.0.1 brings massive performance upgrades via class caching and batched CSS insertions, infinitely chained variants, mandatory security validations for arbitrary values, and new unique features like Runtime Theme Switching and Scoped Mode.
Installation
Jetflow is designed to be added with a single HTML script tag. No package manager needed.
CDN (Recommended)
Add this tag to the <head> of your HTML before any content that uses
utility classes:
<script src="https://cdn.jsdelivr.net/gh/JetflowJS/Jetflow@v1.0.1/jetflow.js"></script>
With a custom config
To use a configuration file, load it before the Jetflow script using a module script. Jetflow will automatically pick up the exported default config:
<!-- 1. Load your config first --> <script type="module" src="jetflow.config.js"></script> <!-- 2. Then load Jetflow --> <script src="https://cdn.jsdelivr.net/gh/JetflowJS/Jetflow@v1.0.1/jetflow.js"></script>
Place the <script> in your <head>, not at the bottom of
<body>. This ensures styles are applied before content is painted, preventing a flash
of unstyled content.
Self-hosted
Download jetflow.min.js from the GitHub repository and host it alongside your project. Useful for
offline use or environments with restricted network access.
<script src="/assets/jetflow.min.js"></script>
Quick Start
Here's everything you need to build a complete page with Jetflow in under a minute:
<head> via CDN.<!DOCTYPE html> <html> <head> <script src="https://cdn.jsdelivr.net/gh/JetflowJS/Jetflow@v1.0.1/jetflow.js"></script> </head> <body> <!-- Flexbox card with dark mode support --> <div class="flex-center min-h-screen bg-gray-50 dark:bg-gray-900"> <div class="flex flex-col gap-4 p-8 rounded-xl border border-gray-200 bg-white shadow-lg dark:border-slate-700 dark:bg-slate-900 max-w-sm w-full"> <h1 class="text-2xl font-bold text-gray-900 dark:text-white"> Hello, Jetflow! </h1> <p class="text-sm text-gray-500 leading-relaxed"> Utility-first CSS with zero build step. </p> <button class="flex-center gap-2 rounded-md bg-orange-500 px-4 py-2 text-sm font-semibold text-white transition hover:bg-orange-600"> Get Started </button> </div> </div> </body> </html>
Configuration
Jetflow works without any configuration. But when you need custom colors, component
shortcuts, or extended spacing — create a jetflow.config.js file and export a default config
object.
export default { darkMode: "media", // "class" | "media" | "both" reset: true, // inject CSS reset theme: { colors: { brand: { light: "#d9efff", mid: "#1479c9", dark: "#0d4f83", } }, spacing: { 18: "4.5rem", 128: "32rem" }, fontSize: { "huge": "5rem" }, screens: { sm: "640px", md: "768px", lg: "1024px" } }, apply: { ".btn-primary": "flex-center gap-2 rounded-md bg-brand-mid px-4 py-2 text-sm text-white shadow-sm transition hover:bg-brand-dark", ".card": "box rounded-lg p-6 shadow-md dark:border-slate-700 dark:bg-slate-900", }, safelist:["hidden", "md:flex", "hover:bg-brand-dark"] };
Utility Classes
Jetflow provides 500+ atomic utility classes. Each class maps to a single CSS declaration. You compose them directly in your HTML — no custom CSS needed for most layouts. Internally, utilities are mapped directly as functions linking them natively to configuration tokens.
<!-- Each class = one CSS property --> <div class="flex items-center justify-between gap-4 p-6 rounded-lg border border-gray-200"> <span class="text-sm font-semibold text-gray-900">Label</span> <button class="px-4 py-2 rounded-md bg-blue-500 text-white text-sm transition hover:bg-blue-600 focus:outline-none focus:ring-2"> Action </button> </div>
Chained Variants (v1.0.1)
Jetflow v1.0.1 introduces robust chained variants with strict ordering (media → selector → pseudo). You can stack variants infinitely:
<!-- Applies blue background only on medium screens, on hover, when focused --> <div class="md:hover:focus:bg-blue-500"></div>
Variant prefixes
Jetflow classes support a range of modifier prefixes to apply styles conditionally:
| Prefix | Applies when | Example |
|---|---|---|
| hover: | Mouse hover | hover:bg-gray-100 |
| focus: | Keyboard / click focus | focus:ring-2 |
| active: | Element is pressed | active:scale-95 |
| dark: | Dark mode active | dark:bg-slate-900 |
| sm: md: lg: xl: 2xl: | Viewport ≥ breakpoint | md:flex-row |
| group-hover: | Parent .group is hovered |
group-hover:opacity-100 |
Dark Mode
Jetflow supports three dark mode strategies, configured via darkMode in your
config. All three modes use the dark: prefix on any utility class.
"class"Class-based.dark class is present on a parent element
(typically <html> or <body>). Toggle it with JavaScript."media"System preferenceprefers-color-scheme: dark media query. Follows the user's OS
preference automatically. (Set as default in v1.0.1 documentation)"both"Class + mediaResponsive Design
Jetflow uses a mobile-first breakpoint system. Unprefixed utilities apply at all sizes; prefixed utilities apply from that breakpoint upward.
| Prefix | Min-width | Target |
|---|---|---|
| — (none) | 0px | All screens (mobile-first default) |
| sm: | 640px | Small tablets and up |
| md: | 768px | Tablets and up |
| lg: | 1024px | Laptops and up |
| xl: | 1280px | Desktops and up |
Arbitrary Values
Need a one-off value that isn't in the default scale? Use bracket notation to pass any CSS value directly — no config changes needed.
<!-- Any safe CSS unit works --> <div class="p-[13px] w-[calc(100%-2rem)] bg-[#1a1a1a]"></div> <!-- With variants --> <div class="md:text-[22px] hover:bg-[rgba(255,95,21,0.12)]"></div> <!-- Shorthand padding (top/bottom left/right) --> <div class="p-[8px_16px]"></div>
Security new
Security is a mandatory priority in Jetflow v1.0.1. All arbitrary values are subjected to strict regex validation before being injected into the DOM.
#fff), rgb/rgba, numbers, and standard CSS units
(px, rem, %, etc.).url(), javascript:, expression(), and
@import are strictly forbidden.If an invalid or unsafe value is detected, Jetflow will silently ignore the class. We NEVER inject raw values without validation to prevent CSS injection attacks.
Scoped Mode new
Jetflow v1.0.1 introduces Scoped Mode, allowing you to restrict utility classes so they only apply inside a designated container. This ensures that utility frameworks don't pollute styling in complex macro environments.
<!-- Styles prefixed globally will only apply inside this scoped wrapper --> <div class="jf-scope-widget bg-white p-4"> <p class="text-blue-500 font-bold">Scoped content</p> </div>
Layout
Display
Flexbox
Grid
Gap
Sizing
Position
Spacing
Jetflow uses a 4px base spacing scale. Each step corresponds to n × 4px (e.g.,
p-4 = 16px, m-8 = 32px).
Padding
Margin
Typography
Font size
| Class | Size | Line-height |
|---|---|---|
| text-xs | 0.75rem | 1rem |
| text-sm | 0.875rem | 1.25rem |
| text-base | 1rem | 1.5rem |
| text-lg | 1.125rem | 1.75rem |
| text-xl | 1.25rem | 1.75rem |
| text-2xl | 1.5rem | 2rem |
| text-3xl | 1.875rem | 2.25rem |
| text-4xl | 2.25rem | 2.5rem |
| text-5xl | 3rem | 1 |
| text-6xl | 3.75rem | 1 |
Font weight
Alignment, decoration & more
Colors
Jetflow ships with a full default palette (slate, gray, zinc, red, orange, amber, yellow,
lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose). Each shade runs
from 50 to 950.
Text color
Background color
Custom colors via config
export default { theme: { extend: { colors: { // Adds: bg-brand-mid, text-brand-dark, etc. brand: { light: "#d9efff", mid: "#1479c9", dark: "#0d4f83", 50: "#eef8ff", 500: "#1479c9", 700: "#0d4f83", } } } } };
After defining these tokens, use them anywhere: bg-brand-mid, text-brand-dark, border-brand-500, ring-brand-mid, and
so on.
Borders & Radius
Border width
Border color
Border radius
Shadows & Rings
Box shadow
Ring (focus outline)
Rings are composable box-shadow utilities designed for focus states. They stack cleanly with other shadow utilities.
<button class="rounded-md shadow-md focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 hover:shadow-lg transition"> Focusable button </button>
Transforms
Jetflow's transform utilities are powered by CSS custom properties and compose cleanly — multiple transform functions don't overwrite each other.
Transform origin
Effects & Filters
Opacity & visibility
Transitions
Filters
Apply & Components
The apply config key lets you create named CSS selectors that expand to a string
of Jetflow utilities. Think of it as a shortcut for commonly repeated patterns — without writing any CSS.
export default { apply: { // Primary button ".btn-primary": "flex-center gap-2 rounded-md bg-brand-mid px-4 py-2 text-sm text-bold text-white shadow-sm transition hover:bg-brand-dark focus:outline-none focus:ring-2 focus:ring-brand-mid focus:ring-offset-2", // Secondary button ".btn-secondary": "flex-center gap-2 rounded-md border border-gray-300 bg-white px-4 py-2 text-sm text-bold text-slate-800 transition hover:bg-gray-50 dark:border-slate-600 dark:bg-slate-900 dark:text-white", // Card ".card": "box rounded-lg p-6 shadow-md dark:border-slate-700 dark:bg-slate-900", // Notice/alert ".notice": "rounded-md border border-amber-200 bg-amber-50 p-[8px_16px] text-sm text-amber-900" } };
Now use these class names directly in your HTML:
<button class="btn-primary">Save Changes</button> <button class="btn-secondary">Cancel</button> <div class="card"> <h2 class="text-lg font-semibold">Title</h2> <p class="text-sm text-gray-500">Card content here.</p> </div> <div class="notice">⚠ Session expires in 5 minutes.</div>
The apply strings are still Jetflow utility classes under the hood — they support responsive
prefixes, dark mode, and arbitrary values just like any other class.
Custom Utilities
The utilities config key registers new atomic utility names that expand to other
Jetflow classes. Unlike apply, these become first-class utilities — they support variants like
hover:, dark:, and breakpoints.
export default { utilities: { // Aliases that expand to class strings "flex-center": "flex items-center justify-center", "flex-between": "flex items-center justify-between", "flex-around": "flex items-center justify-around", "text-bold": "font-bold", "box": "block rounded-md border border-gray-200 bg-white p-4", // Raw CSS object (for properties with no Jetflow equivalent) "text-balance": { "text-wrap": "balance" } } };
The built-in custom utilities — flex-center, flex-between,
text-bold, box — are pre-registered by Jetflow and can be used without any config.
Theming & Tokens
Jetflow's theme system works on a merge principle. Use theme.extend to add
tokens on top of the defaults, or theme directly to replace entire categories.
export default { theme: { extend: { // Add custom color tokens colors: { brand: { mid: "#1479c9", dark: "#0d4f83" } }, // Extend the spacing scale spacing: { 18: "4.5rem", // adds p-18, m-18, gap-18… 128: "32rem" // adds w-128, h-128… }, // Add border radius tokens borderRadius: { "4xl": "2rem" // adds rounded-4xl } } } };
Use theme.extend to preserve Jetflow's default tokens (all 300+ colors, full spacing scale,
etc.) while adding your own. Using theme directly will replace the entire category.
Plugins API
Plugins let you extend Jetflow programmatically. Pass an array of plugin functions in your config — each receives the Jetflow API and can register new utilities, components, or inject raw CSS.
function myPlugin({ addUtility, addComponent, addBase }) { // Register a new utility addUtility("visually-hidden", { position: "absolute", width: "1px", height: "1px", overflow: "hidden", clip: "rect(0,0,0,0)", whiteSpace: "nowrap" }); // Register a component class addComponent(".badge", "inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium"); // Inject base CSS addBase({ "::selection": { background: "#FF5F15", color: "#fff" } }); } export default { plugins: [myPlugin] };
DOM Engine & Performance
Jetflow v1.0.1 features a completely rewritten rendering engine built for extreme
performance. It automatically watches for new nodes added to the DOM after initial load via a strictly
optimized MutationObserver.
- Single Initialization: Scans the DOM once at startup and tracks processed elements
using a
WeakSet. - Optimized Observer: The MutationObserver processes only new or modified nodes, completely avoiding repeated DOM scanning.
- Caching & Deduplication: Parsed classes are mapped and cached. All generated CSS rules are automatically deduplicated.
- Batched Output: Multiple dynamically generated styles are batched into a single
<style>tag insertion to minimize browser repaints.
mutationDebouncems (default: 16)autoStartboolean (default: true)false to control
initialization manually via JetFlow.start().safeliststring[]// Dynamically added elements are styled automatically const card = document.createElement("div"); card.className = "flex flex-col gap-4 p-6 rounded-lg border shadow-md"; document.body.appendChild(card); // ↑ Jetflow detects this and processes it without re-scanning old nodes
Runtime API
Jetflow exposes a global JetFlow object you can use to control the runtime
programmatically.
| Method | Description |
|---|---|
| JetFlow.start() | Begin DOM observation and style generation. Called automatically unless
autoStart: false.
|
| JetFlow.stop() | Stop the MutationObserver. Existing styles are preserved. |
| JetFlow.refresh() | Re-scan the full DOM and regenerate all styles. Useful after bulk DOM manipulations. |
| JetFlow.configure(config) | Merge additional configuration at runtime. Triggers a full refresh. |
| JetFlow.setTheme(theme) | Dynamically update theme tokens and CSS variables at runtime without reloading the page. |
| JetFlow.inspect(element) | Development tool to log parsed classes and generated CSS for a specific element to the console. |
| JetFlow.addClass(cls) | Force-generate CSS for a class string, even if not in the DOM. |
| JetFlow.version | Returns the current Jetflow version string. |
// Stop and restart observation JetFlow.stop(); // ... heavy DOM manipulation ... JetFlow.refresh(); // Inspect parsed elements in development JetFlow.inspect(document.querySelector(".my-btn")); // Add classes that exist only in JS strings JetFlow.addClass("bg-red-500 text-white px-4 py-2 rounded"); // Dynamically update the application theme without reload JetFlow.setTheme({ colors: { brand: "#10b981" } }); console.log(JetFlow.version); // "1.0.0"
Config Reference
All available options for jetflow.config.js:
darkModestring"class", "media", or
"both". Default: "media".
resetbooleantrue.
autoStartbooleantrue.debugbooleanfalse.importantboolean!important to all generated declarations. Default:
false.
mutationDebouncenumber16.theme.screensobjectcontainersobjecttheme.extendobjectcolors, spacing,
borderRadius, fontFamily, and more.
applyobjectutilitiesobjectsafeliststring[]pluginsfunction[]{ addUtility, addComponent, addBase }.
Changelog
v1.0.1Minor Release- Medium-risk vulnerability fix.
Watch the GitHub repository ↗ for release notes and new version announcements.