# gnat/surreal

🗿 Mini jQuery alternative. Dependency-free animations. Locality of Behavior.  Use one element or arrays transparently. Pairs with htmx. Vanilla querySelector() but better!

Repository: https://github.com/gnat/surreal
Canonical: https://ross.abutalabs.com/products/surreal
Homepage: https://gnat.github.io/surreal/example.html
Language: JavaScript
License: MIT
License Family: permissive
Topics: cash, dom, dom-manipulation, jquery, jquery-alternative, jquery-like, jquery-replacement, queryselector, queryselectorall, selector, umbrella, ergonomics, locality-of-behavior, hyperscript, htmx, animation, timeline, vanilla-js, javascript, surreal
Last push: 2026-05-27T13:12:42+00:00

## Health v2 (maintenance only)
Score: 72/100 (v2, computed 2026-09-02T17:46:02.011165+00:00)
- activity 84, release rhythm 40, longevity 100
- inputs: {"age_days": 1551, "days_push": 98, "days_rel": 408, "gap_med": 0.0, "n_releases_24m": 3}
- flags: none
- formula: round(0.45*activity + 0.35*rhythm + 0.20*longevity); archived -> min(score, 10)

## Adoption (not part of the score)
Stars 1731, forks 28 (observed 2026-08-28T04:05:28.719805+00:00)

## What it is
Surreal is a tiny, dependency-free JavaScript library that provides ergonomic jQuery-style DOM selection and manipulation on top of vanilla querySelector. It adds Locality of Behavior helpers like me()/any(), call chaining, and built-in animations and timelines in roughly 320 lines with no build step.

## Use cases
- replace jQuery with a tiny vanilla JS alternative
- avoid typing document.querySelector and addEventListener repeatedly
- add animations and timelines without extra libraries
- use inline scripts with locality of behavior alongside htmx
- query one element or arrays of elements transparently
- write ergonomic DOM manipulation with no build step

## When to choose
- you want jQuery-like ergonomics while staying close to vanilla JS
- you pair htmx or hyperscript and want inline, local scripts
- you need a tiny dependency-free DOM helper with animations

## When to avoid
- you need a full reactive frontend framework with state management
- your project already standardizes on jQuery or a large UI framework
- you need extensive plugin ecosystem or legacy browser support

## Facets
- artifact type: library
- maturity: active
- function: ui-components, animation, developer-tools
- domain: web-development, frontend
- platform: browser
- tags: jquery-alternative, dom-manipulation, locality-of-behavior, vanilla-js, htmx, queryselector, dependency-free, no-build-step, javascript

## Member repositories
- gnat/surreal (main) score 72

## Provenance
- Observed fields: from GitHub, fetched 2026-08-28T04:05:28.719805+00:00.
- Health v2: computed from the inputs above; adoption is never an input.
- Inferred fields (summary, facets, guidance): AI-extracted, prompt v1, taxonomy v1, on 2026-08-30T03:31:42.494579+00:00, confidence not recorded.
  - readme: https://github.com/gnat/surreal (fetched 2026-08-28T04:05:28.719805+00:00, sha 26dabe9ca3f3)
  - homepage: https://gnat.github.io/surreal/example.html (fetched 2026-08-29T11:08:42.055936+00:00, sha 035423f08e44)
- Data as of 2026-08-30T08:39:29.467469+00:00.