diff --git a/www/content/docs.md b/www/content/docs.md index 42713a3c..b6aa748c 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -175,44 +175,23 @@ npm install htmx.org@4.0.0-alpha1 After installing, you’ll need to use appropriate tooling to use `node_modules/htmx.org/dist/htmx.js` (or `.min.js`). For example, you might bundle htmx with some extensions and project-specific code. -### Webpack - -If you are using webpack to manage your javascript: - -* Install `htmx` via your favourite package manager (like npm or yarn) -* Add the import to your `index.js` - -```js -import 'htmx.org'; -``` - -If you want to use the global `htmx` variable (recommended), you need to inject it to the window scope: - -* Create a custom JS file -* Import this file to your `index.js` (below the import from step 2) - -```js -import 'path/to/my_custom.js'; -``` - -* Then add this code to the file: - -```js -window.htmx = require('htmx.org'); -``` - -* Finally, rebuild your bundle - ## AJAX -The core of htmx are two attributes that allow you to issue fetch()-based AJAX requests directly from HTML: +
+htmx 2.0 to 4.0 Changes + +

htmx 4.0 uses the fetch() API instead of XMLHttpRequest. This enables built-in streaming response support and simplifies the implementation of htmx, but does create some significant changes between the two versions.

+ +
+ +At the core of htmx are two attributes that allow you to issue fetch()-based AJAX requests directly from HTML: | Attribute | Description | |----------------------------------------|---------------------------------------------------------------------------------------------------------| | [hx-action](@/attributes/hx-action.md) | Specifies a URL to issue the request to | | [hx-method](@/attributes/hx-method.md) | Specifies the [HTTP Method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods) to use | -They can be used like so: +These attributes can be used like so: ```html +``` + + + Often you will want to confirm an action before issuing a request. htmx supports the [`hx-confirm`](@/attributes/hx-confirm.md) attribute, which allows you to confirm an action using a simple javascript dialog: @@ -716,6 +753,33 @@ resolves with a `true` value to continue ## Attribute Inheritance {#inheritance} +
+htmx 2.0 to 4.0 Changes + + + +**Breaking Change:** Inheritance is now **explicit** using the `:inherited` modifier. + +**In htmx 2.x**, attributes automatically inherited from parent elements. + +**In htmx 4.x**, you must use `hx-attribute:inherited="value"` to inherit from parents. + +**New feature:** Use `:append` modifier to append values to inherited values: +```html +
+ +
+``` + +
+ Unlike htmx 2, in htmx 4 attribute inheritance is _explicit_, rather than _implicit_. Inheritance allows you to "hoist" attributes up the DOM to avoid code duplication. @@ -823,6 +887,33 @@ As such, the normal HTML accessibility recommendations apply. For example: ## Streaming Responses +
+htmx 2.0 to 4.0 Changes + + + +**Major Change:** Server-Sent Events (SSE) are now **built-in** to htmx core. + +**In htmx 2.x**, SSE required the `hx-sse` extension. + +**In htmx 4.x**: +- SSE is built-in, no extension needed +- Any htmx request automatically handles SSE when server responds with `Content-Type: text/event-stream` +- Supports all HTTP methods (GET, POST, PUT, PATCH, DELETE) +- Configure with `hx-stream` attribute (modes: `once`, `continuous`) +- Automatic reconnection with exponential backoff in `continuous` mode +- Page Visibility API integration (pause when tab hidden) + +**No migration needed** if using standard htmx attributes - just remove the extension! + +
+ htmx 4 has built-in support for Streaming Responses Server-Sent Events (SSE). Use the typical `hx-get`, `hx-post`, `hx-put`, `hx-patch`, or `hx-delete` attributes. When the server responds with `Content-Type: text/event-stream` instead of `Content-Type: text/html`, htmx automatically handles the stream. @@ -960,6 +1051,31 @@ page to learn more. ## History Support {#history} +
+htmx 2.0 to 4.0 Changes + + + +**Major Change:** History no longer uses `localStorage` for caching. + +**In htmx 2.x**, history snapshots were stored in localStorage. + +**In htmx 4.x**, htmx issues a full page request when the user navigates back/forward. The server receives an `HX-History-Restore-Request` header and should return the full page HTML. + +**Removed attributes:** +- `hx-history` (no longer needed) +- `hx-history-elt` (no longer needed) + +This change makes history restoration much more reliable and reduces client-side complexity. + +
+ Htmx provides a simple mechanism for interacting with the [browser history API](https://developer.mozilla.org/en-US/docs/Web/API/History_API): If you want a given element to push its request URL into the browser navigation bar and add the current state of the page @@ -1107,6 +1223,42 @@ Please see the [Animation Guide](@/examples/animations.md) for more details on t ## Extensions +
+htmx 2.0 to 4.0 Changes + + + +**Major Change:** Extensions are now globally registered and event-based. + +**In htmx 2.x**, extensions required `hx-ext="extension-name"` on elements. + +**In htmx 4.x**, extensions: +1. Register globally in `htmx.config.extensions` meta tag +2. Use `htmx.defineExtension()` with event handler functions +3. Listen to htmx events (no special extension API) + +**Removed:** `hx-ext` attribute is no longer needed for globally registered extensions. + +**Example:** +```html + +``` + +```javascript +htmx.defineExtension('my-extension', { + 'htmx_before_request': function(elt, detail) { + // Handle event + } +}); +``` + +
+