Framework‑Agnostic Behaviour Primitives

A collection of 103 behaviour primitives – reusable, framework‑agnostic functions and classes that solve common web interaction problems: focus management, dynamic positioning, gesture recognition, drag & drop, virtual scrolling, keyboard navigation, selection, autocomplete, accessibility, and more.

This is not a UI component library. It provides no buttons, no modals, no dropdowns.
Instead, it gives you the reliable building blocks to implement those components yourself – in React, Vue, Svelte, Angular, or vanilla JavaScript.

📖 Live documentation & interactive demos:
https://adnenre.github.io/behaviour-primitive/

📦 Installation

npm install behaviour-primitive

or using pnpm:

pnpm add behaviour-primitive

🚀 Quick Start

Import a primitive by name and use it directly:

import { TabTrap } from "behaviour-primitive";

const modalElement = document.getElementById("my-modal");
const focusTrap = new TabTrap(modalElement);
focusTrap.activate(); // Now Tab key cycles only inside the modal

🧩 What is a “behaviour primitive”?

A behaviour primitive is a pure logic unit that implements a specific interaction pattern:

• Trap keyboard focus inside a modal → TabTrap
• Keep a tooltip attached to a button while scrolling → AutoUpdater
• Detect a two‑finger rotation gesture → RotateDetector
• Manage a dynamic array of form fields → FieldArray

You bring the DOM elements and your own styling. We bring the battle‑tested, accessible, framework‑independent behaviour.

📦 What’s inside?

103 primitives organised into 11 categories:

• Focus Management (8)
• Dynamic Positioning (10)
• Gesture & Touch Recognition (9)
• Drag & Drop (9)
• Virtual & Advanced Scrolling (7)
• Keyboard Navigation (5)
• Selection & List Management (7)
• Autocomplete & Typeahead (5)
• UI State & Transitions (7)
• Accessibility Helpers (4)
• Infrastructure & Utilities (34)

See the full list in the documentation site linked above.

🛠️ Usage Examples

Focus Trap

import { TabTrap, FocusLock } from "behaviour-primitive";

const modal = document.getElementById("modal");
const trap = new TabTrap(modal);
trap.activate();

Dynamic Positioning with AutoUpdater

import { AutoUpdater } from "behaviour-primitive";

const tooltip = document.getElementById("tooltip");
const button = document.getElementById("button");

function positionTooltip() {
  const rect = button.getBoundingClientRect();
  tooltip.style.top = rect.bottom + 5 + "px";
  tooltip.style.left = rect.left + "px";
}

const updater = new AutoUpdater(positionTooltip, { scroll: true, resize: true });
updater.start();

Gesture Detection

import { SwipeDetector } from "behaviour-primitive";

const element = document.getElementById("swipe-area");
const detector = new SwipeDetector(element, (direction) => {
  console.log(`Swiped ${direction}`);
});

🌐 Framework‑agnostic design

All primitives are written in plain TypeScript and do not depend on any framework. Use them wherever JavaScript runs:

• React – call primitives inside useEffect or event handlers.
• Vue – use inside mounted or setup with ref.
• Svelte – call within onMount or actions.
• Angular – use inside directives or components.
• Vanilla JS – directly in your script.

♿ Accessibility

Every primitive is built with accessibility in mind:

• ARIA roles and attributes (where applicable)
• Keyboard navigation support (Tab, Enter, Escape, Arrow keys)
• Focus management (trapping, restoring, redirecting)
• Screen reader announcements via live regions

📖 Full Documentation

Interactive demos and detailed documentation for every primitive are available at:
👉 https://adnenre.github.io/behaviour-primitive/

You can also browse the source code in src/primitives/ on GitHub.

🤝 Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

📄 License

MIT

🙏 Acknowledgements

Inspired by real‑world UI problems encountered while building component libraries without a framework.
This project focuses on how things behave, not how they look.