Add support for partial responses for htmx in Ruby on Rails controllers.
Install the gem and add it to the application's Gemfile by executing:
$ bundle add rails-htmx
Providing the assets for htmx is out of the scope of this library and the assets gems have been deprecated (along with Sprockets) by Rails.
Note: You might want to disable Turbo (and turbo-rails) if your application has it already installed.
Instead is recommended to install htmx from the official sources:
Add the script to your application.html.erb layout file:
<script src="https://unpkg.com/htmx.org@1.9.5" integrity="sha384-xcuj3WpfgjlKF+FXhSQFQ0ZNr39ln+hwjN3npfM9VBnUskLolQAcN80McRIVOPuO" crossorigin="anonymous"></script>Check the htmx docs to make sure that you're using the latest version of the package
Add the htmx.org package using Yarn:
yarn add htmx.organd then import it on your app/javascript/application.js:
import "htmx.org"Pin the dependency to the into the importmap:
bin/importmap pin htmx.organd then import it on your app/javascript/application.js:
import "htmx.org"By default, the rails-htmx prevents the render of the application layout in
your controllers and instead returns only the yielded view for the
requests that have the HX-Request header present.
Additionally, rails-htmx modify redirects in non-GET and non-POST requests to
return 303 (See Other) as status code instead of 302 to handle XHR redirects correctly.
For more information about how to use htmx please consult the htmx docs.
In certain cases might want to return a full view (e.g in a login page) instead of a partial yielded view, you can do this calling the prevent_htmx! method in your controller actions or in an callback:
before_action :prevent_htmx!, if: -> { some_condition? }
def login
prevent_htmx!
# ...
endIf you have additional content you want to always be returned with your htmx requests,
you can override htmx_layout in your controller and specify a layout to render
(by default, it's false)
class ApplicationController < ActionController::Base
def htmx_layout
'htmx'
end
endYou can use the hx helper to simplify the generation of the attributes
in your views, e.g:
<%= button_to "Update post", @post, method: :delete, data: { "hx-patch": url_for(@post), "hx-swap": "outerHTML", "hx-target": "body" } %>can be rewritten using the hx helper:
<%= button_to "Update post", @post, method: :delete, data: hx(patch: url_for(@post), swap: "outerHTML", target: "body") %>Those are some tips for using htmx with Rails.
Add the X-CSRF-Token to the hx-headers attributes in your <body> tag so it's added by
default in XHR requests done by htmx:
<body hx-headers='{"X-CSRF-Token": "<%= form_authenticity_token %>"}'>You can use the data- prefix to make easier adding the htmx attributes with the Rails helpers:
<%= link_to "Home", root_path, data: { "hx-swap": "outerHTML" } %>You can use the default Rails helpers without modifications in your markup with the htmx Boosting feature:
<div hx-boost="true">
<%= link_to "New post", new_post_path %>
</div>Add the hx-target="body", hx-swap="outerHTML", and hx-push-url="true" to
update the body with the content of the document retrieved after
redirection and push the new URL into the browser location history.
<%= button_to "Destroy post", @post, method: :delete, data: { "hx-delete": url_for(@post), "hx-swap": "outerHTML", "hx-target": "body" "hx-push-url": "true" } %>by default, non-200 responses are not swapped into the DOM, this behavior can be changed using one of the next options:
-
Using the response-targets extension and setting the target for the status code, e.g:
<button hx-post="/register" hx-target="#response-div" hx-target-5*="#serious-errors" hx-target-422="#response-div" hx-target-404="#not-found"> Register! </button>
or using Rails helpers:
<%= button_to "Register", register_path, data: hx(post: register_path, target: "#response-div", "target-5*": "#serious-errors", "target-422": "#response-div" , "target-404": "#not-found") %>
For default Rails forms your might want to set
hx-target-422to the same value ashx-targetin that way the form will be swapped with the new form with validation error messages. Check the extension for more details and examples. -
Handle the
htmx:beforeSwapevent in order to modify the swap behavior:document.body.addEventListener('htmx:beforeSwap', function(evt) { if(evt.detail.xhr.status === 404){ alert("Error: Could Not Find Resource"); } else if(evt.detail.xhr.status === 422){ // allow 422 responses to swap as we are using this as a signal that // a form was submitted with bad data and want to rerender with the // errors evt.detail.shouldSwap = true; // set isError to false to avoid error logging in console evt.detail.isError = false; } });
Check the htmx docs for details
In order to get the extensions working you need to pin the extensions in your config/importmap.rb:
# config/importmap.rb
# ...
pin "htmx.org", to: "https://unpkg.com/htmx.org@1.9.5"
pin "htmx.org/dist/ext/", to: "https://unpkg.com/htmx.org@1.9.5/dist/ext/"Then you can load extensions in your application.js:
// app/javascript/application.js
import "htmx.org"
import "htmx.org/dist/ext/method-override"
import "htmx.org/dist/ext/ajax-header"Using rollup does not require any changes.
For esbuild and webpack you need to load htmx globally before of importing the extensions, this can be done creating a custom
file and injecting htmx to the window scope on it:
// app/javascript/application.js
import "./htmx.js"
import "htmx.org/dist/ext/method-override"
import "htmx.org/dist/ext/ajax-header"// app/javascript/htmx.js
import htmx from "htmx.org"
window.htmx = htmxrails-htmx is released under the MIT License.