htmx/www/content/migration-guide-htmx-1.md

+++ title = "htmx 1.x → htmx 2.x Migration Guide" +++

The purpose of this guide is to provide instructions for migrations from htmx 1.x to htmx 2.x. We place a very high value on backwards compatibility, so in most cases this migrations should require very little, if any, work.

• If you are still using the legacy hx-ws and hx-sse attributes, please upgrade to the extension versions (available in 1.x)

• Default Changes

  • If you want to retain the 1.0 behavior of "smooth scrolling" by default, revert htmx.config.scrollBehavior to 'smooth'
  • If you want DELETE requests to use a form-encoded body rather than parameters, revert htmx.config.methodsThatUseUrlParams to ["get"] (it's a little crazy, but DELETE, according to the spec, should use request parameters.)
  • If you want to make cross-domain requests with htmx, revert htmx.config.selfRequestsOnly to false

• If you are using htmx in a module setting, we now provide module-type specific files for all three of the major JavaScript module types: /dist/htmx.esm.js, /dist/htmx.umd.js & /dist/htmx.amd.js

• all extensions have been removed from the core htmx distribution and are distributed separately on their own website

• Convert any hx-on attributes to their hx-on: equivalent:

     <button hx-get="/info" hx-on="htmx:beforeRequest: alert('Making a request!')
                                   htmx:afterRequest: alert('Done making a request!')">
      Get Info!
     </button>
  

  becomes:

     <button hx-get="/info" hx-on:htmx:before-request="alert('Making a request!')"
                            hx-on:htmx:after-request="alert('Done making a request!')">
      Get Info!
     </button>
  Note that you must use the kebab-case of the event name due to the fact that attributes are case-insensitive in HTML.
  

• The htmx.makeFragment() method now always returns a DocumentFragment rather than either an Element or DocumentFragment

• If you are an extension author and your extension was using selectAndSwap method from internal API, it was removed and replaced with swap method, which is available from both internal and public htmx APIs

  To do swap using new method, you need to simply use

  let content = "<div>Hello world</div>"; // this is HTML that will be swapped into target
  let target = api.getTarget(child);
  let swapSpec = api.getSwapSpecification(child);
  api.swap(target, content, swapSpec);
  

swap method documentation is available on JS API Reference

IE is no longer supported in htmx 2.0, but htmx 1.x continues to support IE and will be supported for the foreseeable future.

Upgrade Music

This is the official htmx 1.x -> 2.x upgrade music: