SimpleCSS
Download

⚡ Ajax

(HTMX-like behavior with data-ajax-* attributes)

The Ajax utility is a lightweight vanilla JS helper that provides HTMX-like behavior using simple data-ajax-* attributes. It uses event delegation and works for dynamically added elements.

It supports GET and POST requests, target selection, partial swaps, fragment extraction and hook events (before, success, error, after).

💠 Example

(Simple GET button)

This content will be replaced by the AJAX response.

🧩 How to use

Add one of the following attributes on your element:

  • data-ajax-get="URL": sends a GET request.
  • data-ajax-post="URL": sends a POST request.
  • data-ajax-trigger="eventName": event that triggers the request (for example click, submit, input).
  • data-ajax-target="#selector": CSS selector of the element to update with the response. If not found, the source element is used as fallback.
  • data-ajax-swap="innerHTML|outerHTML|replace": how the HTML is injected. Default is innerHTML.
  • data-ajax-select="CSS selector": optional fragment selector. If set, only the matching element’s innerHTML from the response is used.
  • data-ajax-value="{'key': 'value'}": JSON object appended to the form data before sending.

For POST requests, the nearest <form> is used to build the FormData. For GET requests, the form data is converted to query parameters and appended to the URL.

🧩 How it works

The Ajax class sets up global event delegation using an EventManager wrapper. For each data-ajax-trigger value found in the DOM, it registers a listener on document.

On each event:

  • It finds the closest element with data-ajax-trigger matching the event type.
  • It resolves the URL and HTTP method from data-ajax-get / data-ajax-post.
  • It builds the FormData from the closest form or from the element itself.
  • It applies optional data-ajax-value by parsing the JSON and appending each key/value to the form data.
  • For GET requests, it appends parameters to the URL; for POST, it sends them as the body.
  • It sends a fetch request with X-Requested-With: XMLHttpRequest and expects an HTML response.
  • On success, it optionally extracts a fragment with data-ajax-select and swaps the target content according to data-ajax-swap.
  • On error, it logs messages and injects a fallback error message.

🧩 Hook events

You can run inline expressions or functions at different stages of the lifecycle using:

  • data-ajax-event-before
  • data-ajax-event-success
  • data-ajax-event-error
  • data-ajax-event-after

The value is a list of function names or JS expressions separated by ;. For each expression:

  • If window[expr] is a function, it is called as fn(context, element).
  • Otherwise a new function is evaluated: new Function('context', 'element', expr)(context, host).

Example:

data-ajax-event-success="onAjaxSuccess;console.log('Done')"

Here, onAjaxSuccess(context, element) must exist on window. Then a simple console.log is executed.

⚙️ Attributes reference

Attribute Description
data-ajax-get URL for GET requests. Form data is appended as query parameters.
data-ajax-post URL for POST requests. Form data is sent in the request body.
data-ajax-trigger Event name that triggers the request (e.g. click, submit, input).
data-ajax-target CSS selector of the element to update with the response. If missing or not found, the source element is used.
data-ajax-swap Swap strategy: innerHTML (default), outerHTML, replace. Unknown values fall back to innerHTML.
data-ajax-select CSS selector of the element to extract from the HTML response. If found, its innerHTML is used. If not, the whole response is used.
data-ajax-value JSON-like string that is parsed and appended to the form data. Single quotes are allowed and converted internally.
data-ajax-event-before Hook executed before the request is sent.
data-ajax-event-success Hook executed after a successful response.
data-ajax-event-error Hook executed when the request fails.
data-ajax-event-after Hook executed at the very end (success or error).