'
+ );
+ });
+});
diff --git a/test/index.html b/test/index.html
index 86113143..15aa3ef4 100644
--- a/test/index.html
+++ b/test/index.html
@@ -134,6 +134,9 @@
+
+
+
diff --git a/www/docs.md b/www/docs.md
index 8f2b4483..8d8e9a4d 100644
--- a/www/docs.md
+++ b/www/docs.md
@@ -952,6 +952,7 @@ Htmx includes some extensions that are tested against the htmx code base. Here
| [`client-side-templates`](/extensions/client-side-templates) | support for client side template processing of JSON responses
| [`path-deps`](/extensions/path-deps) | an extension for expressing path-based dependencies [similar to intercoolerjs](http://intercoolerjs.org/docs.html#dependencies)
| [`class-tools`](/extensions/class-tools) | an extension for manipulating timed addition and removal of classes on HTML elements
+| [`multi-swap`](/extensions/multi-swap) | allows to swap multiple elements with different swap methods
See the [extensions page](/extensions#included) for a complete list.
@@ -1386,7 +1387,7 @@ listed below:
| `htmx.config.wsReconnectDelay` | defaults to `full-jitter`
| `htmx.config.disableSelector` | defaults to `[disable-htmx], [data-disable-htmx]`, htmx will not process elements with this attribute on it or a parent
| `htmx.config.timeout` | defaults to 0 in milliseconds
-| `htmx.config.defaultFocusScroll` | if the focused element should be scrolled into view, defaults to false and can be overriden using the [focus-scroll](/attributes/hx-swap/#focus-scroll) swap modifier.
+| `htmx.config.defaultFocusScroll` | if the focused element should be scrolled into view, defaults to false and can be overridden using the [focus-scroll](/attributes/hx-swap/#focus-scroll) swap modifier.
diff --git a/www/essays/when-to-use-hypermedia.md b/www/essays/when-to-use-hypermedia.md
new file mode 100644
index 00000000..6946c648
--- /dev/null
+++ b/www/essays/when-to-use-hypermedia.md
@@ -0,0 +1,200 @@
+---
+layout: layout.njk
+title: When To Use Hypermedia?
+---
+
+# When Should you Use Hypermedia?
+
+> The trade-off, though, is that a uniform interface degrades efficiency, since information is transferred in a
+> standardized form rather than one which is specific to an application's needs. The REST interface is designed to be
+> efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an
+> interface that is not optimal for other forms of architectural interaction.
+
+_-Roy Fielding, _
+
+We are obviously big fans of hypermedia and think that it can address, at least in part, many of the problems that the web
+development world is facing today:
+
+* Hypermedia is typically less complex than an SPA approach would be for a given problem
+* Hypermedia allows your application API to be much more aggressively changed and optimized
+* Hypermedia takes pressure off adopting a particular back-end technology
+
+With [htmx](/) and the additional UX possibilities that it gives you, many modern web applications can be built
+using HTML and the hypermedia paradigm.
+
+With that being said, as with all technical choices, there are tradeoffs associated with hypermedia. In this article
+outlines when we think hypermedia *is* likely to be a good fit, and when it *is not* likely to be a good fit.
+
+## Transitional Applications & Hypermedia
+
+Before we get into the details of when hypermedia is a good choice, we'd like to clarify that adopting hypermedia is not
+an [either/or](https://en.wikipedia.org/wiki/Either/Or) decision when building a web application. Even the most Single-y
+of Single Page Applications utilizes hypermedia after all, as a bootstrap mechanism, to start the application.
+
+In his talk, [Have SPAs Ruined The Web](https://www.youtube.com/watch?v=860d8usGC0o), Rich Harris gives us the term
+"Transitional" Applications, that is applications that mix both hypermedia and non-hypermedia (SPA) concepts. We
+have responded to Mr. Harris' talk [in more detail here](/essays/a-response-to-rich-harris/), but suffice to say we agree
+with him that a pragmatic "Transitional" approach to web development is best: use the right tool for the job.
+
+Where we would likely disagree with Mr. Harris is just where "the line" is between what can be achieved with hypermedia
+and the point at which it is better to reach for a more involved client-side library. We feel that, with htmx, hypermedia
+can go much, much further than many web developers believe is possible. And that, for many applications, it can
+address many or all of their UX needs.
+
+## Hypermedia: A Good Fit If...
+
+So, when *is* hypermedia a good choice for an application and/or feature?
+
+### If Your UI is mostly text & images
+
+In [The Mother Of All htmx Demos](/essays/a-real-world-react-to-htmx-port/), David Buillot of Contexte shows how replacing
+react with htmx lead to a 67% reduction in the total codebase, along with numerous other eye-popping results.
+
+As much as we would like to say that every team moving from react to htmx would experience these results, the fact is that the
+Contexte web application is *extremely amenable* to the hypermedia style.
+
+What makes Contexte so perfect for hypermedia is that it is a media-oriented web application, showing articles consisting
+of text and images for reading. It has a sophisticated filtering mechanism and other niceties, but the crux of the
+application is displaying and categorizing articles. This is exactly the sort of thing that hypermedia was designed to
+do, and that is why htmx and hypermedia worked so well for this application.
+
+### If Your UI is CRUD-y
+
+Another area where hypermedia has a long track-record of success is [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete)-y
+web applications, in the [Ruby on Rails](https://rubyonrails.org/) style. If your main application mechanic is showing
+forms and saving the forms into a database, hypermedia can work very well.
+
+And, with htmx, it can also be [very smooth](https://htmx.org/examples/click-to-edit/), and not just constrained
+to a simple [detail view](https://htmx.org/examples/edit-row/) approach.
+
+### If Your UI is "nested", with updates mostly taking place within well-defined blocks
+
+One area where hypermedia can start to go a little wobbly is when you have UI dependencies that span structural
+areas. A good example of this, and one that often comes up when criticizing the hypermedia approach, is the issue
+count number shown in the ["Issues" tab](https://github.com/bigskysoftware/htmx/issues) in Github. When you close
+an issue on Github, for a long time, the tab count did not update properly, because the tab itself wasn't replaced
+by the hypermedia request.
+
+"Ah ha!", exclaims the SPA partisan, "See, even GitHub can't get this right!"
+
+Well, yes, but there are [a few techniques for making this work](https://htmx.org/examples/update-other-content/), and,
+if you watch their talk, Contexte handled this situation easily, using events.
+
+But, let us grant that this is an area where the hypermedia approach can get into trouble. To avoid this problem, one
+strategy is to colocate and next the dependent elements for a given resource within an area in the application.
+
+Consider a contact application whose detail screen for displaying and editing a contact has:
+
+* An area for basic contact information
+* An area for emails
+* An area for phone numbers
+
+The UI could be laid out in the following manner:
+
+
+
+Where each sub-section has its own dedicated hypermedia end-points:
+
+* `/contacts//details` for the first name/last name/ etc. info
+* `/contacts//emails` for the email section
+* `/contacts//phonenumbers` for the phone numbers section
+
+The crux here is that the email count and phone count are co-located with their collections, which allows you to
+[target](/attributes/hx-target) just that particular area for update when a modification is made to the respective
+collections. All the data dependencies are co-located within a single area that can be updated via a single, simple
+and obvious target, and that don't interfere with one another.
+
+Each area effectively forms a sort of server-side component, independent of the other areas on the screen, and they are
+all nested within a broader contact detail user interface.
+
+#### UI Driven Hypermedia APIs
+
+Note that our hypermedia API (that is, our end-points) in this case is _driven by the UI_, we have a particular layout
+that we want to achieve and we adapt our API to that. If the UI changed, we would have no qualms with completely changing
+the API to satisfy the new requirements. This is a [unique aspect](https://htmx.org/essays/hateoas/) of developing with
+hypermedia, and we [discuss it in more detail here](https://htmx.org/essays/hypermedia-apis-vs-data-apis/).
+
+Of course, there may be UI requirements that do not allow for grouping of dependent element in this manner and, if
+the techniques [mentioned above](https://htmx.org/examples/update-other-content/) aren't satisfactory, then it may be
+time to consider an alternative approach.
+
+### If You need "deep links" and good first-render performance
+
+A final area where hypermedia outperforms other options is when you need "deep links", that is, links into your
+application that go beyond the landing page, or when you need excellent first-render performance.
+
+Since hypermedia is the natural language of the web, and since browsers are very good at rendering HTML given a URL,
+using this approach is hard to beat for "traditional" web features such as these.
+
+## Hypermedia: Not A Good Fit If...
+
+Of course, there are times when hypermedia isn't a good choice. Let's review some of them:
+
+### If Your UI has many dynamic interdependencies
+
+As we discussed above in the section on "nested" UIs, one area where hypermedia can have trouble is when there are
+many UI dependencies spread across your UI and you can't afford to "update the whole UI". This is what Roy Fielding was
+getting at in the quote at the top of this article: the web was designed for large-grain hypermedia data transfers, not
+lots of small data exchanges.
+
+Particularly difficult for hypermedia to handle is when these dependencies are dynamic, that is, they depend on information
+that cannot be determined at render-time. A good example of this is something like a spreadsheet: a user can enter an
+arbitrary function into a cell and introduce all sorts of dependencies on the screen. Something like Google Sheets
+would be a poor fit for the hypermedia approach.
+
+(Note, however, that for many applications, the ["editable row"](https://htmx.org/examples/edit-row/) pattern is an
+acceptable alternative to more general spreadsheet-like behavior, and does play well with hypermedia, by isolating the
+edits within a bounded area.)
+
+### If you require offline functionality
+
+The hypermedia distributed architecture leans heavily on the server side for rendering representations of resources.
+When a server is down or unreachable, the architecture will obviously have trouble. It is possible to use Web Workers
+to handle offline requests, and it is possible to detect when a hypermedia application is offline and show a message.
+
+But if your application requires full functionality in an offiline environment, then the hypermedia approach is not
+going to be acceptable.
+
+### Your UI state is updated extremely frequently
+
+Another situation where hypermedia is not going to be a good approach is if your UI state is updated frequently. A good
+example is an online game that needs to capture mouse movements. Putting a hypermedia network request in-between a mouse
+move and a UI update will not work well, and you would be far better off writing your own client-side state management
+for the game and syncing with a server using a different technology.
+
+Of course, your game may also have a setting page, and that setting page might be better done with hypermedia than
+whatever solution you use for the core of your game. There is nothing wrong with mxing and matching approaches!
+
+### Your team is not on board
+
+A final reason to not choose hypermedia isn't technical, but rather sociological: currently, hypermedia simply isn't
+in favor in web development. Many companies have adopted react as their standard library for building web applications.
+Many developers and consultants have bet their careers on it. Many hiring managers have never heard of hypermedia, let
+alone htmx, but put react on every job they post out of habit.
+
+While this is frustrating, it is also a real phenomenon and should be borne in mind with humility. Although Contexte
+was able to rewrite their application quickly and every effectively in htmx, not all teams are as small, agile and
+passionate, nor are all applications such slam dunks for the approach. It may be better to adopt hypermedia around
+the edges, perhaps for internal tools first, to prove its value first, before taking a broader look at it.
+
+## Conclusion
+
+We are often asked what sorts of applications **wouldn't** htmx be good for. Again, we prefer to think about things on a
+feature-by-feature basis, and we hope that this article has given you some design points to think about when
+considering hypermedia and htmx.
+
+But, at a high level and to close with some easy-to-remember applications:
+
+We think that applications like Twitter or GMail could be built very effectively using hypermedia due to their
+focus on text-and-images, but that applications like Google Sheets or Google Maps could not due to their arbitrary
+data dependencies and UI paradigms.
+
+Of course, the vast majority of web applications are nowhere near the scale of these examples, and almost every web
+application has parts where the hypermedia approach could be better: simpler, faster and cleaner.
+
+Having hypermedia as a tool in your tool-chest will improve your ability to address engineering problems as a web
+developer, even if you don't reach for it as your favorite hammer, like we do. There is a
+good [theoretical basis](https://htmx.org/essays/a-real-world-react-to-htmx-port/) for the approach, as well as
+[practical benefits for many applications](https://htmx.org/essays/a-real-world-react-to-htmx-port/).
+
+Not the least being: this is how the web is supposed to work!
\ No newline at end of file
diff --git a/www/extensions.md b/www/extensions.md
index 9940d3c1..02a656d7 100644
--- a/www/extensions.md
+++ b/www/extensions.md
@@ -72,9 +72,11 @@ See the individual extension documentation for more details.
| [`event-header`](/extensions/event-header) | includes a JSON serialized version of the triggering event, if any
| [`include-vals`](/extensions/include-vals) | allows you to include additional values in a request
| [`json-enc`](/extensions/json-enc) | use JSON encoding in the body of requests, rather than the default `x-www-form-urlencoded`
+| [`idiomoroph`](https://github.com/bigskysoftware/idiomorph) | an extension for using the idimorph morphing algorightm as a swapping mechanism
| [`loading-states`](/extensions/loading-states) | allows you to disable inputs, add and remove CSS classes to any element while a request is in-flight.
| [`method-override`](/extensions/method-override) | use the `X-HTTP-Method-Override` header for non-`GET` and `POST` requests
| [`morphdom-swap`](/extensions/morphdom-swap) | an extension for using the [morphdom](https://github.com/patrick-steele-idem/morphdom) library as the swapping mechanism in htmx.
+| [`multi-swap`](/extensions/multi-swap) | allows to swap multiple elements with different swap methods
| [`path-deps`](/extensions/path-deps) | an extension for expressing path-based dependencies [similar to intercoolerjs](http://intercoolerjs.org/docs.html#dependencies)
| [`preload`](/extensions/preload) | preloads selected `href` and `hx-get` targets based on rules you control.
| [`remove-me`](/extensions/remove-me) | allows you to remove an element after a given amount of time
diff --git a/www/extensions/multi-swap.md b/www/extensions/multi-swap.md
new file mode 100644
index 00000000..b12eff1a
--- /dev/null
+++ b/www/extensions/multi-swap.md
@@ -0,0 +1,71 @@
+---
+layout: layout.njk
+title: htmx - multi-swap extension
+---
+
+## The `multi-swap` extension
+
+This extension allows you to swap multiple elements marked with the `id` attribute from the HTML response. You can also choose for each element which [swap method](/docs/#swapping) should be used.
+
+Multi-swap can help in cases where OOB ([Out of Band Swaps](/docs/#oob_swaps)) is not enough for you. OOB requires HTML tags marked with `hx-swap-oob` attributes to be at the TOP level of HTML, which significantly limited its use. With OOB is not possible to swap multiple elements arbitrarily placed and nested in the DOM tree.
+
+It is a very powerful tool in conjunction with `hx-boost` and `preload` extension.
+
+#### Usage
+
+1. Set `hx-ext="multi-swap"` attribute on ``, on some parent element, or on each action element that should trigger an action (typically anchors or buttons).
+2. On your action elements set `hx-swap="multi:ID-SELECTORS"`, e.g. `hx-swap="multi:#id1,#id2:outerHTML,#id3:afterend"`.
+3. If you're not using e.g. `hx-get` to enable HTMX behavior, set `hx-boost="true"` on your action elements, or on some parent element, so that all elements inherit the hx-boost setting.
+
+Selectors must be separated by a comma (without surrounding spaces) and a colon with the desired swap method can optionally be placed after the selector. Default swap method is `innerHTML`.
+
+```html
+
+ <-- simple example how to swap #id1 and #id2 from /example by innerHTML (default swap method) -->
+
+
+ <-- advanced example how to swap multiple elements from /example by different swap methods -->
+ Click to swap #id1 and #id2, extend #id3 content and delete #id4 element
+
+
Old 1 content
+
Old 2 content
+
Old 3 content
+
Old 4 content
+
+```
+
+**Real world example with preloading**
+
+The use case below shows how to ensure that only the `#submenu` and `#content` elements are redrawn when the main menu items are clicked. Thanks to the combination with the preload extension, the page, including its images, is preloaded on `mouseover` event.
+
+```html
+
+
+
+
+
+
+ ...
+