ActionView::Helpers::UrlHelper

button_to

API docs (Rails 8.1.4.1) ↗
def button_to(name = nil, options = nil, html_options = nil, &block)

Description

Creates a <form> that contains only a <button>.

Arguments

Changing a value updates the ERB and HTML.

= nil
The content of the <button>, escaped. Defaults to the action value. To pass only options, set this to nil.
The URL used as the action of the <form>. It is passed to url_for, so the result depends on the value:
  • A string: used as the action as is. Route helpers such as article_path(1) return a URL string, so they are handled the same way.
  • A model object: builds the object's URL from the routes. If the :method option in html_options is omitted and the object is persisted, adds a hidden <input> with _method set to patch.
  • A hash: builds the URL from the routes ({ controller: "articles", action: "index" } gives /articles).
  • :back: the request's Referer if present, otherwise javascript:history.back(). A per-form CSRF token cannot be generated for javascript:history.back(), so this raises NoMethodError (unless method is :get or authenticity_token is false, in which case no token is generated). On this site, requests to the rendering API have this page as their Referer, so the result is this page's URL.
  • false: omits action.
html_options= {}
Depending on the value:
  • :get: sets method="get" on the <form> and omits the hidden <input> for the CSRF token.
  • :patch, :put, :delete: sets method="post" on the <form> and adds a hidden <input> for _method before the <button>. Rails treats an incoming POST with _method as a request of that method, such as PATCH.
  • :post: sets method="post" on the <form>.
  • Omitted: same as :patch if the options argument is a persisted object, otherwise same as :post.
Strings are not downcased, so "DELETE" or "GET" produces method="post" without _method. Unlike link_to, no data-method is added to the <button>.
{q: "ruby", page: 2}
Adds a hidden <input> for each key and value in the given hash, with the key as its name and the value as its value. They are sorted by name and placed after the <button> and the CSRF token. An array value produces a name such as tags[], and a hash value one such as user[name]. A nil value omits value.
{id: "article_form"}
The given hash becomes HTML attributes of the <form>. These keys are handled differently:
  • class: replaces the default button_to class. A string "class" key produces two class attributes (class="c" class="button_to").
  • method and action: ignored. The <form>'s method comes from the :method option in html_options, and its action from the options argument.
"inline"
Sets the class of the <form>. If the :form option in html_options also has a class key, that value is used instead, and this option becomes a form_class attribute of the <button> as is.
false omits the hidden <input> for the CSRF token. A string is used as the value of the hidden token input. When the :method option in html_options is :get, the token is never added, regardless of this option.
true adds data-remote="true" to the <form>. In apps without Rails UJS (the default since Rails 7), this HTML attribute does nothing.
"button"
Ignored. The type of the <button> is always submit.
Common options

Rails handles these options the same way in every helper. Options the HTML spec does not allow on the <button>, and ones this site considers rarely used, are not listed here.

Shared by all helpers

true adds disabled="disabled"; false omits it. The same goes for every HTML attribute in Rails' list (BOOLEAN_ATTRIBUTES), such as readonly, required and autofocus: any value other than false or nil adds it as attr="attr".
{active: true, hidden: false}
A hash gives the keys whose values are not false or nil, joined with spaces. An array gives its elements joined with spaces, after removing nil, false and empty strings (including whitespace-only strings).
{controller: "tags", tags_suggestions_value: ["ruby", "rails"]}
A hash adds data-* attributes, with _ in the keys converted to -. Array and hash values are converted to JSON strings.
{describedby: ["name_help", "name_error"], invalid: false}
Like :data, adds aria-* attributes. Array values are joined with spaces, leaving out nil and empty strings (nothing is added if none remain). For a hash value, the keys whose values are not false or nil are joined with spaces.
Any other html_options become HTML attributes of the <button>; those with a nil value are left out.

ERB

Changes from the previous output: Added Removed Changed


          

        


        

          

            
HTML

          

          

            
            

          

        


        

          

            
Preview

            

              
              
                
Interacting with the preview updates the form submission.


            

          


          

            
Form submission

            

              
Form data

              

                
namevalue

                
              

              

                Request body
                
Content-Type: 

                

              

              

                
params

                

              

                
This site shows the CSRF token as (hidden). The real token is a long string that changes on every render.