ActionView::Helpers::FormBuilder

button

API docs (Rails 8.1.4.1) ↗

def button(value = nil, options = {}, &block)

Description

Creates a type="submit" <button> whose content is based on the outer form's model.

Arguments

Changing a value updates the ERB and HTML.

value = nil

StringSymbol

Accepts:

A string: used as the content of the <button>.
A symbol: adds name and id, and the content stays the default. Unlike other helpers, it does not read the object's value and adds no value attribute.
A hash: treated as options (so the second argument, options, can be left out).
Omitted: the content is the first of the following that exists:
1. The helpers.submit.article.create translation (update if the record is persisted; likewise below)
2. The helpers.submit.create translation
3. Create followed by the model name (model_name.human), as in Create Article

options= {}

:type = "submit"

"button"

Sets type to the given value as is. Defaults to type="submit".

:name = "button"

"commit"

Defaults to name="button". When the value argument is a symbol, builds the name from it. This option overrides both. nil omits name.

:id = nil

"draft_button"

When the value argument is a symbol, builds the id from it. This option overrides it. nil omits id.

:value = nil

"true"

Sets value to the given value as is. By default, no value is added.

:formmethod = nil

:delete:get

Depending on the value:

Anything other than post and get, such as :delete or :patch: sets formmethod to post, adds name="_method", and sets value to the given value. Rails reads _method in the incoming POST and handles the request as a DELETE or PATCH.
:get and :post: used as formmethod as is.

When the :name or :value option is given, or the first argument, value, is a symbol, any value is used as formmethod as is, without being rewritten.

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

:disabled

truefalse

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".

:class

{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).

:data

{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.

:aria

{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 options become HTML attributes of the <button>; those with a nil value are left out.

&block= nil

nil

do
  Save <b>draft</b>
end

do |text|
  <b><%= text %></b>
end

With a block, uses the block's output as the content of the <button>. The block receives (as text) the value argument if it is a string, and otherwise the default content.

Context

New @articlePersisted @article

The @article passed to the outer form. When the value argument is omitted, the content is Create Article for a new record and Update Article for a persisted one.

ERB

Changes from the previous output: Added Removed Changed

Controller action

@article = Article.new

Controller action

@article = Article.find(1)

HTML

Preview

Interacting with the preview updates the form submission.

Form submission

Form data

name	value

Request body

Content-Type:

params

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