CairnJS — Zero-Dependency Reactive UI Framework & Component Suite

Build reactive, framework-agnostic web applications and components with zero external dependencies. Use with React, Vue, Svelte, Angular, standard Web Components, or vanilla HTML/JS.

🌐 Live Documentation & Interactive Playground: cairnjs.vercel.app
📦 GitHub Organization: github.com/cairn-js | Main Repo: github.com/cairn-js/cairnjs
🤖 Prompting AI Assistants? Copy-paste llms.txt or docs/ai-prompt.md into ChatGPT, Claude, Cursor, or Gemini for 100% accurate CairnJS code generation.

🔄 Official Migration to @cairn-js Organization

CairnJS has officially migrated to the @cairn-js organization on GitHub and NPM!

• GitHub: github.com/cairn-js/cairnjs
• NPM Core: @cairn-js/core
• Owner / Maintainer: EldrexDelosReyesBula

Upgrading from @cairn-js/core:

# Update package
npm uninstall @cairn-js/core
npm install @cairn-js/core

# With official plugins
npm install @cairn-js/core @cairn-js/coat @cairn-js/ui

Update your imports:

// Before
import { state, button, mount } from '@cairn-js/core';

// After
import { state, button, mount } from '@cairn-js/core';

Core Architectural Principles

CairnJS is designed around five pragmatic engineering priorities:

| Principle | Architectural Approach | Practical Benefit | | :--- | :--- | :--- | | ⚡ Performance | Fine-grained signals update target DOM properties directly. | Eliminates Virtual DOM reconciliation overhead during updates. | | 🛡️ Reliability | Subtree fault isolation via errorBoundary and graceful fallbacks. | Component runtime errors are isolated to prevent total tree crashes. | | ✨ Simplicity | Zero external runtime dependencies and modular subpath packaging. | Minimal attack surface and clean dead-code elimination via ESM. | | 🎯 Ergonomics | Standard JavaScript, native HTML element builders, and zero required build steps. | Works out-of-the-box in <script type="module"> or via npm. | | 🏔️ Stability | Adherence to standard web APIs and Semantic Versioning 2.0.0. | Predictable behavior without compiler churn or hidden breaking changes. |

Why CairnJS?

CairnJS combines the simplicity of standard DOM functions with the power of a complete modern UI framework:

• Fine-Grained Reactivity: Signals (state, computed, effect) update exact text nodes and style properties with zero Virtual DOM overhead.
• 250+ HTML & UI Element Builders: Complete HTML 1.0 to Beyond coverage (150 standard + 100 Cairn UI components).
• Complete CSS1–CSS4 Coat System: Zero-dependency CSS engine supporting nested selectors (&:hover, & > child), @keyframes, @media, @container, and class utilities (cx, classNames).
• Direct HTML String Content: Direct HTML string child parsing (div({}, '<strong>Notice:</strong>...')), { html: '...' } prop, and safe XSS sanitization (cairn.sanitize, cairn.safe).
• 50+ Accessible UI Primitives: Modals, Drawers, Toast queues, Command Palettes (Cmd+K), Context Menus, Steppers, Accordions, and Data Tables.
• Declarative Form Validation: Schema-based validation engine with validators and dynamic repeating rows (useFieldArray).
• Accessible Overlays: Automatic focus trapping (createFocusTrap), z-index layering (tokens.zIndex), and escape dismissal.
• Complete Motion Suite: Spring physics, gestures, timeline sequencing, and particle kinematics.
• Micro-Core Architecture: Ultra-lean ESM subpaths with the core bundle under 5.0 KB minified (< 2.0 KB gzipped).
• Universal Cross-Framework Bridges: Seamlessly export to React (toReact), Vue (toVue), Svelte, Angular, or W3C Custom Elements.

import { state, div, button, p, coat, mount } from '@cairn-js/core';

const count = state(0);

const app = div({
    coat: {
        padding: '24px',
        background: '#0f172a',
        borderRadius: '16px',
        color: '#f8fafc',
        border: '1px solid rgba(255,255,255,0.1)'
    }
},
    p(() => `Count: ${count.value}`),
    button('+ Increment', {
        onclick: () => count.value++,
        coat: {
            padding: '8px 16px',
            background: '#38bdf8',
            color: '#0f172a',
            fontWeight: '600',
            borderRadius: '8px',
            cursor: 'pointer',
            '&:hover': { background: '#0284c7', color: '#fff' }
        }
    })
);

mount('#app', app);

📦 Installation & Universal Subpath Delivery

Package Manager (npm / pnpm / yarn)

npm install @cairn-js/core

Granular Subpath Imports (ESM & Bundlers)

Every subpath is fully resolved, typed, and independently tree-shakeable:

// Surgical modular imports with zero unnecessary code bundled
import { state } from '@cairn-js/core/state';
import { computed } from '@cairn-js/core/computed';
import { effect } from '@cairn-js/core/effect';
import { div, button, input } from '@cairn-js/core/dom';
import { mount } from '@cairn-js/core/mount';
import { coat } from '@cairn-js/core/style';
import { animate, spring } from '@cairn-js/core/animation';
import { createForm, validators } from '@cairn-js/core/form';
import { router, Link } from '@cairn-js/core/router';
import { events, on, emit } from '@cairn-js/core/events';
import { Button, Input, Card } from '@cairn-js/core/components';

CommonJS Support (Node.js & Legacy Bundlers)

const { state, mount, div, button } = require('@cairn-js/core');
const { computed } = require('@cairn-js/core/computed');

Multi-CDN (Zero Build & Instant Prototyping)

1. Modern ESM Script

<!-- Primary High-Speed Direct CDN -->
<script type="module">
    import { state, button, mount } from 'https://cairnjs.vercel.app/cdn/cairn.min.js';

    const count = state(0);
    mount('#app', button(
        () => `Count: ${count.value}`,
        { onclick: () => count.value++ }
    ));
</script>

2. Classic Script Tag (IIFE / Zero Tooling)

<!-- Exposes window.Cairn and window.cairn globally -->
<script src="https://cdn.jsdelivr.net/npm/@cairn-js/[email protected]/dist/index.global.js"></script>
<script>
    const { state, mount, button } = window.Cairn;
    const count = state(0);
    mount('#app', button(() => `Count: ${count.value}`, { onclick: () => count.value++ }));
</script>

Global Edge CDN Mirrors

| Provider | Canonical URL | Subpath Support | |---|---|---| | Direct Vercel Edge | https://cairnjs.vercel.app/cdn/cairn.min.js | Direct file | | esm.sh | https://esm.sh/@cairn-js/[email protected] | https://esm.sh/@cairn-js/[email protected]/state | | jsDelivr Global | https://cdn.jsdelivr.net/npm/@cairn-js/[email protected]/dist/index.min.js | .../dist/state.min.js | | unpkg | https://unpkg.com/@cairn-js/[email protected]/dist/index.min.js | .../dist/state.min.js |

// Subpath imports directly via CDN in browser
import { state } from 'https://esm.sh/@cairn-js/[email protected]/state';
import { button } from 'https://esm.sh/@cairn-js/[email protected]/dom';
import { coat } from 'https://esm.sh/@cairn-js/[email protected]/style';

🚀 Feature Highlights & Code Recipes

1. Declarative Form Validation & Dynamic Arrays

import { createForm, validators, useFieldArray, div, button, mount } from '@cairn-js/core';

const userForm = createForm({
    fields: {
        email: { label: 'Email', type: 'email', default: '' },
        password: { label: 'Password', type: 'password', default: '' }
    },
    schema: {
        email: [validators.required(), validators.email()],
        password: [validators.required(), validators.minLength(8)]
    },
    onSubmit: async (values) => {
        console.log('Form Submitted Successfully:', values);
    }
});

// Dynamic repeating field rows
const tags = useFieldArray([{ label: 'Engineering' }]);
tags.append({ label: 'Design' });

2. Accessible Overlays, Focus Trapping & Modals

import { Modal, ConfirmDialog, Drawer, Toast, NotificationCenter } from '@cairn-js/core';

// 1. Accessible Dialog Modal
const settingsModal = Modal({
    title: 'User Settings',
    content: 'Configure preferences and notifications.',
    closeOnEscape: true
});

// 2. Asynchronous Promise Confirmation
async function deleteItem() {
    const ok = await ConfirmDialog.confirm({
        title: 'Delete Item?',
        message: 'This action cannot be undone.',
        variant: 'danger'
    });
    if (ok) Toast.success('Item deleted');
}

// 3. Global Notification Center
const bellButton = NotificationCenter.Button();
const historyDrawer = NotificationCenter.Panel();

3. Power-User Navigation & Menus

import { CommandPalette, ContextMenu, DataTable } from '@cairn-js/core';

// Global Spotlight Search (Ctrl+K / Cmd+K)
const palette = CommandPalette({
    hotkey: true,
    actions: [
        { title: 'Open Documentation', group: 'Navigation', onSelect: () => window.location.href = 'https://cairnjs.vercel.app' },
        { title: 'New Project', group: 'Actions', onSelect: () => console.log('New project created') }
    ]
});

3. Interactive Data Table with Sorting, Search & Pagination

import { DataTable, mount } from '@cairn-js/core';

const usersTable = DataTable({
    columns: [
        { key: 'name', title: 'User Name', sortable: true },
        { key: 'role', title: 'Security Role', sortable: true },
        { key: 'status', title: 'Account Status', render: (val) => `<span class="badge">${val}</span>` }
    ],
    data: [
        { name: 'Eldrex Bula', role: 'Maintainer', status: 'Active' },
        { name: 'Sarah Jenkins', role: 'Architect', status: 'Active' },
        { name: 'Alex Rivera', role: 'Developer', status: 'Pending' }
    ],
    pageSize: 5,
    searchable: true
});

mount('#app', usersTable);

4. Internationalization (i18n) & RTL Auto-Sync

import { createI18n } from '@cairn-js/core';

const i18n = createI18n({
    locale: 'en',
    messages: {
        en: { welcome: 'Welcome, {name}!' },
        ar: { welcome: 'مرحبا {name}!' } // Automatically toggles <html dir="rtl">
    }
});

console.log(i18n.t('welcome', { name: 'Eldrex' }));

5. Universal Framework Bridges & Web Components

import { defineCustomElement, cairnToReact, cairnToVue } from '@cairn-js/core';

// W3C Standard Custom Element (<my-widget>)
defineCustomElement('my-widget', MyComponent, ['title']);

// React & Vue Wrappers
export const ReactWidget = cairnToReact(MyComponent);
export const VueWidget = cairnToVue(MyComponent);

6. First-Class Plugin & Lifecycle Architecture

Extend the core runtime with functional or object plugins, or intercept lifecycle events with zero overhead:

import { use, hooks } from '@cairn-js/core';

// Register functional or object plugin with lifecycle support
use({
    name: 'custom-logger',
    install(cairn, options) {
        cairn.log = (...args) => console.log('[App]', ...args);
    },
    uninstall(cairn) {
        delete cairn.log;
    }
});

// Subscribe to native lifecycle hooks
hooks.on('beforeMount', (node, container) => {
    console.log('Mounting component tree...');
});

📚 Component Catalog

| Category | Available Components & Primitives | | :--- | :--- | | Layout | Box, Container, Grid, Stack, Center, Cluster, Split, AspectRatio, Show, Hide, Divider, Spacer | | Forms & Inputs | createForm, validators, useFieldArray, NumberInput, PasswordInput, ColorPicker, DropZone, Rating, SegmentedControl, Select, Textarea, Checkbox, Radio, Toggle, Slider, Autocomplete, Combobox | | Overlays & Feedback | Modal, ConfirmDialog, Drawer, Toast, NotificationCenter, createFocusTrap, overlayStack, Alert, Progress, Skeleton, Spinner, EmptyState | | Navigation | CommandPalette, ContextMenu, Breadcrumbs, Pagination, Stepper, Tabs, Navbar, Sidebar, Menu, Dropdown, router, Link | | Data Display | DataTable, DataGrid, Table, Accordion, Timeline, Tree, Card, Badge, Avatar, Tag, Tooltip, Popover, CodeBlock | | Hooks & Device | useMediaQuery, useHotkeys, useClipboard, useInView, useResize, fullscreen, a11y.audit | | Graphics & Motion | createCanvas2D, createScene3D, shapes, spring, physics, timeline, particles, gesture | | Dev Tools | createPlayground, docs, studio, ai, iteration |

📄 License

MIT License © 2026 Eldrex Bula & CairnJS Contributors.