{"id":13878172,"url":"https://github.com/guilleiguaran/rails-htmx","last_synced_at":"2025-08-28T23:32:33.863Z","repository":{"id":177760322,"uuid":"656998243","full_name":"guilleiguaran/rails-htmx","owner":"guilleiguaran","description":"htmx for Rails","archived":false,"fork":false,"pushed_at":"2023-09-14T18:22:01.000Z","size":42,"stargazers_count":79,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-12-19T23:14:08.277Z","etag":null,"topics":["htmx","rails","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guilleiguaran.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-06-22T05:10:49.000Z","updated_at":"2024-11-23T02:35:08.000Z","dependencies_parsed_at":"2024-03-13T05:18:35.358Z","dependency_job_id":"c6fc17c1-d23a-4cb4-a443-3d0e56fcadbe","html_url":"https://github.com/guilleiguaran/rails-htmx","commit_stats":null,"previous_names":["guilleiguaran/rails-htmx"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guilleiguaran%2Frails-htmx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guilleiguaran%2Frails-htmx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guilleiguaran%2Frails-htmx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guilleiguaran%2Frails-htmx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guilleiguaran","download_url":"https://codeload.github.com/guilleiguaran/rails-htmx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231307051,"owners_count":18355964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["htmx","rails","ruby"],"created_at":"2024-08-06T08:01:41.816Z","updated_at":"2024-12-26T03:34:41.961Z","avatar_url":"https://github.com/guilleiguaran.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# htmx for Rails\n\nAdd support for partial responses for htmx in Ruby on Rails controllers.\n\n![fullstack-1](https://github.com/guilleiguaran/rails-htmx/assets/160941/8b9307af-111a-4af0-92de-218aac07797f)\n\n\n## Installation\n\nInstall the gem and add it to the application's Gemfile by executing:\n\n    $ bundle add rails-htmx\n\n\n## Installing htmx\n\nProviding the assets for htmx is out of the scope of this library and\nthe assets gems have been deprecated (along with Sprockets) by Rails.\n\nNote: You might want to disable Turbo (and turbo-rails) if your application has it\nalready installed.\n\nInstead is recommended to install htmx from the official sources:\n\n### Via CDN\n\nAdd the script to your application.html.erb layout file:\n\n```html\n\u003cscript src=\"https://unpkg.com/htmx.org@1.9.5\" integrity=\"sha384-xcuj3WpfgjlKF+FXhSQFQ0ZNr39ln+hwjN3npfM9VBnUskLolQAcN80McRIVOPuO\" crossorigin=\"anonymous\"\u003e\u003c/script\u003e\n```\n\nCheck the [htmx docs](https://htmx.org/docs/#installing) to make sure that you're using the latest\nversion of the package\n\n### Using a JS Bundler (e.g jsbundling-rails or webpacker)\n\nAdd the htmx.org package using Yarn:\n\n```bash\nyarn add htmx.org\n```\n\nand then import it on your `app/javascript/application.js`:\n\n```javascript\nimport \"htmx.org\"\n```\n\n### Using Import Maps (e.g importmap-rails)\n\nPin the dependency to the into the importmap:\n\n```bash\nbin/importmap pin htmx.org\n```\n\nand then import it on your `app/javascript/application.js`:\n\n```javascript\nimport \"htmx.org\"\n```\n\n## Usage\n\nBy default, the `rails-htmx` prevents the render of the application layout in\nyour controllers and instead returns only the yielded view for the\nrequests that have the `HX-Request` header present.\n\nAdditionally, `rails-htmx` modify redirects in non-GET and non-POST requests to\nreturn 303 (See Other) as status code instead of 302 to handle XHR redirects correctly.\n\nFor more information about how to use htmx please consult the [htmx docs](https://htmx.org/docs/).\n\n### Preventing htmx requests\n\nIn certain cases might want to return a full view (e.g in a login page) instead\nof a partial yielded view, you can do this calling the prevent_htmx!\nmethod in your controller actions or in an callback:\n\n```ruby\n  before_action :prevent_htmx!, if: -\u003e { some_condition? }\n\n  def login\n    prevent_htmx!\n    # ...\n  end\n```\n\n### Custom Layouts\n\nIf you have additional content you want to always be returned with your htmx requests,\nyou can override `htmx_layout` in your controller and specify a layout to render\n(by default, it's `false`)\n\n```ruby\nclass ApplicationController \u003c ActionController::Base\n  def htmx_layout\n    'htmx'\n  end\nend\n```\n\n### The `hx` helper for views.\n\nYou can use the `hx` helper to simplify the generation of the attributes\nin your views, e.g:\n\n```erb\n\u003c%= button_to \"Update post\", @post, method: :delete, data: { \"hx-patch\": url_for(@post), \"hx-swap\": \"outerHTML\", \"hx-target\": \"body\" } %\u003e\n```\n\ncan be rewritten using the `hx` helper:\n\n```erb\n\u003c%= button_to \"Update post\", @post, method: :delete, data: hx(patch: url_for(@post), swap: \"outerHTML\", target: \"body\") %\u003e\n```\n\n\n## Tips\n\nThose are some tips for using htmx with Rails.\n\n### Add the CSRF Token to the htmx requests\n\nAdd the `X-CSRF-Token` to the `hx-headers` attributes in your `\u003cbody\u003e` tag so it's added by\ndefault in XHR requests done by htmx:\n\n```erb\n\u003cbody hx-headers='{\"X-CSRF-Token\": \"\u003c%= form_authenticity_token %\u003e\"}'\u003e\n```\n\n### Using the data prefix\n\nYou can use the `data-` prefix to make easier adding the htmx attributes with the Rails helpers:\n\n```erb\n\u003c%= link_to \"Home\", root_path, data: { \"hx-swap\": \"outerHTML\" } %\u003e\n```\n\n### Boosting Rails helpers\n\nYou can use the default Rails helpers without modifications in your markup with the htmx\n[Boosting feature](https://htmx.org/docs/#boosting):\n\n```erb\n\u003cdiv hx-boost=\"true\"\u003e\n  \u003c%= link_to \"New post\", new_post_path %\u003e\n\u003c/div\u003e\n```\n\n### Redirect after PUT/PATCH/DELETE (30x status)\n\nAdd the `hx-target=\"body\"`, `hx-swap=\"outerHTML\"`, and `hx-push-url=\"true\"` to\nupdate the body with the content of the document retrieved after\nredirection and push the new URL into the browser location history.\n\n```erb\n\u003c%= button_to \"Destroy post\", @post, method: :delete, data: { \"hx-delete\": url_for(@post), \"hx-swap\": \"outerHTML\", \"hx-target\": \"body\" \"hx-push-url\": \"true\" } %\u003e\n```\n\n### XHR errors handling\n\nby default, non-200 responses are not swapped into the DOM, this\nbehavior can be changed using one of the next options:\n\n1. Using the [response-targets extension](https://htmx.org/extensions/response-targets/)\n   and setting the target for the status code, e.g:\n\n    ```html\n    \u003cbutton hx-post=\"/register\"\n            hx-target=\"#response-div\"\n            hx-target-5*=\"#serious-errors\"\n            hx-target-422=\"#response-div\"\n            hx-target-404=\"#not-found\"\u003e\n        Register!\n    \u003c/button\u003e\n    ```\n\n   or using Rails helpers:\n\n   ```erb\n   \u003c%= button_to \"Register\", register_path, data:\n        hx(post: register_path, target: \"#response-div\", \"target-5*\": \"#serious-errors\", \"target-422\": \"#response-div\" , \"target-404\": \"#not-found\") %\u003e\n   ```\n\n   For default Rails forms your might want to set `hx-target-422` to the same value as `hx-target`\n   in that way the form will be swapped with the new form with validation error messages.\n   Check the extension for more details and examples.\n\n2. Handle the `htmx:beforeSwap` event in order to modify the swap\n   behavior:\n\n   ```javascript\n   document.body.addEventListener('htmx:beforeSwap', function(evt) {\n    if(evt.detail.xhr.status === 404){\n        alert(\"Error: Could Not Find Resource\");\n    } else if(evt.detail.xhr.status === 422){\n        // allow 422 responses to swap as we are using this as a signal that\n        // a form was submitted with bad data and want to rerender with the\n        // errors\n        evt.detail.shouldSwap = true;\n\n        // set isError to false to avoid error logging in console\n        evt.detail.isError = false;\n    }\n   });\n   ```\n\n  Check the [htmx docs](https://htmx.org/docs/#modifying_swapping_behavior_with_events) for details\n\n\n### Using htmx extensions in module environments.\n\n#### importmap-rails\n\nIn order to get the extensions working you need to pin the extensions in your `config/importmap.rb`:\n\n```ruby\n# config/importmap.rb\n# ...\npin \"htmx.org\", to: \"https://unpkg.com/htmx.org@1.9.5\"\npin \"htmx.org/dist/ext/\", to: \"https://unpkg.com/htmx.org@1.9.5/dist/ext/\"\n```\n\nThen you can load extensions in your application.js:\n\n```javascript\n// app/javascript/application.js\nimport \"htmx.org\"\nimport \"htmx.org/dist/ext/method-override\"\nimport \"htmx.org/dist/ext/ajax-header\"\n```\n\n#### jsbundling-rails\n\nUsing rollup does not require any changes.\n\nFor esbuild and webpack you need to load `htmx` globally before of importing the extensions, this can be done creating a custom\nfile and injecting `htmx` to the window scope on it:\n\n```javascript\n// app/javascript/application.js\nimport \"./htmx.js\"\nimport \"htmx.org/dist/ext/method-override\"\nimport \"htmx.org/dist/ext/ajax-header\"\n```\n\n```javascript\n// app/javascript/htmx.js\nimport htmx from \"htmx.org\"\nwindow.htmx = htmx\n```\n\n## License\nrails-htmx is released under the [MIT License](https://opensource.org/license/mit/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguilleiguaran%2Frails-htmx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguilleiguaran%2Frails-htmx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguilleiguaran%2Frails-htmx/lists"}