About this site

Rails Helper Helper lets you run Rails' Action View helpers and see what they do. Pass arguments and options to see the resulting HTML, how the browser displays it, and what the form sends. The name means a helper for Rails' helpers.

About the output

The HTML is rendered from the ERB on the server by Rails 8.1.4.1, the same way as an ordinary view.
The params are what Rails builds on the server from the values the preview form sends.
You can choose only the values set up for each page. The ERB does not accept arbitrary Ruby code.
Rails is configured with load_defaults 8.1. Where the output depends on configuration, it reflects these defaults.
This site has no database, so the persisted object you can choose for form_with's model (Article.find(1)) is a stand-in returned by the model's find.

About the descriptions

The option descriptions are based on the actionview source and the actual output. For options with the same name as an HTML attribute, such as min and placeholder, the description says so when Rails changes the value or adds other HTML attributes.

The descriptions were written in Japanese. The English version is translated from the Japanese and may contain unnatural phrasing or shifts in meaning.

“Common options” are split into three groups, by the helpers they apply to.

Shared by …_field: Helpers whose names end in _field, such as text_field and email_field (those that inherit from Tags::TextField)
Shared by form helpers: Form controls that build name and id. FormHelper builds them from the object name and the attribute name (Tags::Base), and FormTagHelper from the name argument
Shared by all helpers: All helpers that output tags (the rules of TagHelper)

On the textarea and rich_textarea pages, the options shared by …_field that they handle the same way (placeholder) are shown as “Shared with …_field and others”.

What the pages leave out

This section covers Rails behavior that the pages leave out, for example because it is too detailed. These items were not checked as closely as the pages and may contain more mistakes.

Shared by form helpers

multiple: true appends [] to the name and adds the multiple attribute in other FormHelper helpers too, not just file_field (checkbox only appends []). In FormTagHelper, only select_tag appends []. This lets several elements with the same name send multiple values. However, it was designed for elements such as select and file inputs, where a single element sends several values. Other helpers are not meant to be used this way, so among the …_field pages, only file_field shows it.
object, index, namespace, skip_default_ids and allow_method_names_outside_object are options that form_with and fields_for pass to the form builder methods. You do not pass them to each helper yourself, so the helper pages leave them out (namespace, index, skip_default_ids and allow_method_names_outside_object are on the form_with page). nil for index adds [] instead of an index (text_field(:user, :name, index: nil) → name="user[][name]" id="user__name").
A ? at the end of the attribute name is removed from the name and id (text_field(:user, :admin?) → name="user[admin]" id="user_admin").
If object_name is in the "user[]" format, adds the object's to_param to the name and id as an index.
When the object's value goes into value, the value before type casting is used (the string exactly as the user typed it). If you enter "abc" in a text_field for a numeric attribute and the form is redisplayed with an error, value is "abc" (because it reads <attribute>_before_type_cast). However, date_field, datetime_field, time_field, month_field and week_field use the type-cast value, reformatted, so if an unreadable value is entered and the form is redisplayed, there is no value attribute.
With settings from before load_defaults 8.1 (config.action_view.remove_hidden_field_autocomplete set to false), also adds autocomplete="off" to hidden <input> elements. However, the hidden <input> elements of DateHelper (created with use_hidden, discard_year and the like) always get autocomplete="off", whatever the setting.
If the object has an error on that attribute, wraps the element in <div class="field_with_errors"> (hidden <input> elements are not wrapped). config.action_view.field_error_proc changes how it is wrapped.
If options include type, …_field sets the type attribute to it (text_field(:user, :name, type: "email") → type="email"). For checkbox and radio_button, a type in options is overridden by checkbox or radio.
If namespace is given to form_with or similar, the id is the namespace value even when id: nil is given.
If object_name differs from the model name, the translations for placeholder and label are also looked up under the model name (helpers.placeholder.<model name>.<attribute>). For an Active Model model, activemodel.attributes is used instead of activerecord.attributes.
If name is given in options together with multiple: true, no [] is appended and the given value is used as is (the same goes for name in the html_options of select, collection_checkboxes and others). To send multiple values, write it as q[].
Passing an endless range to in of number_field or range_field raises RangeError, and a float range that excludes its end (1.0...2.5) raises TypeError. If both in and within are given, within becomes an HTML attribute.

Shared by all helpers

Escapes the content and HTML attribute values. Strings marked html_safe (such as the output of other helpers) are not escaped (except that " in an HTML attribute value becomes ").
Boolean attributes (such as disabled) are omitted when the value is false or nil, and added otherwise, even for the string "false". For other attributes (those not in the BOOLEAN_ATTRIBUTES list), false is converted to a string too, giving values such as title="false"; they are left out only when the value is nil.
In aria:, true and false become "true" and "false".
Passing something other than a hash to data: adds a plain data attribute. When the attribute name is written out in full ("data-foo_bar": 1), _ is not replaced and the value is not converted to JSON.

checkbox

If the :checked option is omitted, compares the object's value with the checked_value argument. How it compares depends on the type (true/false, strings, arrays, etc.).
With multiple: true, checked_value is appended to the id after replacing spaces and . with _, removing punctuation other than - and _, and downcasing it (Yes Please gives article_published_yes_please). If options include id, nothing is appended to the id, and the given value is used as is.
As with disabled and the like, checkbox_tag and radio_button_tag add checked even for "true" or 1.

checkbox_tag

Unlike checkbox, does not add a hidden <input>.
After name, takes up to three arguments: value, checked and options. Passing four or more raises an ArgumentError.

radio_button

If tag_value is an empty string or nil, adds checked even without an object.

radio_button_tag

name and value are required. After them, takes up to two arguments: checked and options. Passing three or more raises an ArgumentError.

DateHelper

Month names come from the date.month_names translation. use_short_month: true uses the short names (date.abbr_month_names), and an array of 12 names passed to use_month_names is used instead.
Raises NoMethodError if the translation for the date order (date.order) is missing: Rails passes default: [] intending an empty array as the fallback, but I18n treats it as a list of fallback keys and returns a "translation missing" string instead. Rails ships English translations for the order and for the prompts (datetime.prompts).
If with_css_classes gets a partial hash ({ year: "y" }), adds an empty class="" to the month and day <select> elements left out of the hash.
Raises ArgumentError if start_year and end_year are more than 1000 years apart (max_years_allowed changes the limit).
Passing discard_type: true to helpers with several <select> elements (date_select, select_date, etc.) gives every <select> the same name (user or date), so only the last value ends up in params. That is why discard_type is shown only on pages such as select_year.
Passing prefix to helpers with an object, such as date_select, uses the given value instead of object_name as the prefix of the name and id (prefix: "x" gives x[birthday(1i)]). A given field_name is overridden by method.
When passing a hash as the first argument (date or datetime) of helpers such as select_date, the keys for minutes and seconds are min and sec. With the keys minute and second, no <option> gets selected.
Passing the matching discard_* (discard_day: true for select_day) to a helper that creates a single <select>, such as select_year, creates a hidden <input>, as use_hidden: true does.
Passing include_position: true to a helper that creates a single <select>, such as select_year, appends the position, such as (1i), to the name and id (date[year(1i)]). This option is meant for internal use by date_select and others.
If several month text options are given together, only the first of use_month_numbers, use_two_digit_numbers, add_month_numbers and month_format_string is used. For the day, day_format comes before use_two_digit_numbers.
distance_of_time_in_words gives about 1 hour from 44 minutes 30 seconds, about 2 hours from 89 minutes 30 seconds, 1 day from 23 hours 59 minutes 30 seconds, 2 days from 42 hours, about 1 month from 29 days 23 hours 59 minutes 30 seconds, and about 1 year from 365 days.

email_field

With multiple: true, the browser sends a single comma-separated value, so params gets an array with one element. Comma-separated email addresses seem rarely needed, so the page leaves this out.

label

The block receives a LabelBuilder: translation returns the translated string, and object returns the form's object (label(:user, :plan) { |b| "#{b.translation} *" }).
The name option shared by form helpers is dropped, and multiple becomes a plain HTML attribute.
Adding a translation for a :value (helpers.label.user.plan.premium) makes helpers.label.user.plan a hash instead of a string, so label(:user, :plan) without :value converts that hash to a string and uses it as the content ({premium: "Premium"}).

Helpers without a page

cdata_section returns a <![CDATA[…]]> string. In HTML, the browser reads it as a comment, so it cannot be shown in the HTML section.
csp_meta_tag creates a <meta> with the CSP nonce. This site does not configure CSP, so it creates nothing.

csrf_meta_tags

The content of the csrf-token <meta> is a long string that changes on every render, so this site masks it as (hidden).

translate

This site's config/locales/examples/ja.yml and en.yml hold the example translations for the translate page. The page shows the file for its language, as is, above the ERB pane.

url_for, current_page?, link_to_unless_current

Requests to this site's rendering API are POST /api/render, so rendering with them as is would make current_page? always false. These three pages therefore render with the request for opening GET /articles?page=2, shown above the ERB pane.
This site's resources :articles in config/routes.rb (ArticlesController) exists only so the examples on pages such as url_for and form_with can build URLs. Opening them returns nothing.
url_for adds no port when port is 80 for http or 443 for https.
Passing subdomain: false to url_for removes the subdomain (blog.example.com becomes example.com). If the host is an IP address, subdomain and domain are ignored.
url_for treats params.permit(…) (ActionController::Parameters) like a hash. Without permit, it raises ActionController::UnfilteredParameters.
If the current controller is in a namespace (such as api/params), url_for looks for controller in the same namespace. Starting it with /, as in "/articles", looks outside the namespace.
current_page? decodes %20 and the like before comparing (+ is not decoded to a space). The query string is compared as a string, so a different order returns false.
In link_to_unless_current, check_parameters: true or method in the options hash is used by current_page? and removed from the URL. method in html_options does not affect whether it is the current page.

AssetTagHelper

This site's app/assets/images/logo.png, logo@2x.png, app/assets/javascripts/application.js and app/assets/stylesheets/application.css are assets for the page examples. They exist only so that the helpers can build digested paths, as in a real app. audios/chime.mp3 and videos/clip.mp4 in app/assets, and sound.mp3, sound.ogg, movie.mp4 and movie.webm in public, are short audio and video clips for the audio_tag and video_tag previews to play. The files in the assets and in public differ in content, so you can tell which one was loaded. photo.png and photo.webp in public are images that show which one the image_tag, picture_tag and image_submit_tag previews loaded.
favicon_link_tag's source defaults to "favicon.ico", which is not among this site's assets, so omitting it raises Propshaft::MissingAssetError. The page therefore always passes it.
javascript_include_tag and stylesheet_link_tag also add an HTTP Link header to the response if config.action_view.preload_links_header is true (load_defaults 6.1 and later). javascript_include_tag does not add it when defer is given. preload_link_tag always adds it, whatever the setting. The :preload_links_header option (javascript_include_tag and stylesheet_link_tag only; preload_link_tag outputs it as a plain HTML attribute) and the :nopush option change only this header, not the HTML, so the pages do not cover them.
Passing extname: false to javascript_include_tag and stylesheet_link_tag looks up the asset without adding the extension, which raises Propshaft::MissingAssetError.
On its own, Rails merges duplicate sources passed to javascript_include_tag and stylesheet_link_tag. Propshaft overrides both helpers and passes the sources to Rails one at a time, so in an app that uses Propshaft, like this site, passing the same string twice outputs two <script> or <link> tags (javascript_include_tag("application", "application")). This can happen when the list of sources is built in code.
stylesheet_link_tag also takes nonce, as javascript_include_tag does (true for the CSP nonce, false for none, and a string as is). This site does not configure CSP, so the page does not cover it.

asset_path, asset_url

If config.relative_url_root is set (for an app served from a subdirectory), it is prepended to the path unless the source is a URL or already starts with it. The same goes for tag helpers such as image_tag. It is nil on this site.
host (and config.asset_host) can also be a proc. It is called with the path, and its return value is used as the host (if it takes a second argument, the current request is passed too; if it returns nil, asset_path adds no host and asset_url adds the current request's).

button_to

With a block, each argument moves up one position, and the block's output becomes the content of the <button> (button_to("/articles", class: "x") do … end). The pages do not cover the block form.
In apps where config.action_view.button_to_generates_button_tag is false (before load_defaults 7.0), creates <input type="submit"> instead of <button> and sets its value to the name argument. This site uses true.
Setting config.action_view.prepend_content_exfiltration_prevention to true prepends HTML such as  to the <form> to close any attributes and tags left open. form_tag and form_with do the same. This site uses the default, false.

link_to

With a block, each argument moves up one position, and the block's output becomes the content (link_to("/articles", class: "x") do … end). The pages do not cover the block form.
An href in html_options is used instead of the URL from options.

link_to_if, link_to_unless

With a block, returns the block's output when it does not create the <a>. The block receives the name argument, or name, options and html_options if it takes two or more arguments. When the <a> is created, the block is ignored. The pages do not cover the block form.

phone_to, sms_to

With a block, the block's output becomes the content of the <a>, as in mail_to. The pages do not cover the block form.

mail_to

With a block, the block's output becomes the content of the <a> (mail_to("me@example.com") do … end). If the name argument is also given, name is ignored. The pages do not cover the block form.

TextHelper

With a block, highlight calls the block for each match instead of using highlighter, and replaces the match with the block's output (unlike \1 in highlighter, neither the match nor the output is escaped). With a block, truncate appends the block's output, but only when it truncates the text (the output does not count toward the length, and is escaped unless it is html_safe, even with escape: false). The pages do not cover the block form.
cycle returns the given values one at a time, in order, each time it is called (for example, to color table rows alternately). A single call does not show this, so there is no page for it.
If truncate's length is shorter than omission, it returns just omission (three characters, ..., even with length: 2). separator also accepts a regular expression.
simple_format adds no <br /> to newlines at the start and end of the text. \r\n and \r also count as newlines.
If word_wrap's break_sequence contains \1 or \0, it is read as a replacement pattern, and the helper returns nil.
If pluralize's count is nil, it writes 0 (0 people).
excerpt strips whitespace from both ends of the result. If text or phrase is nil, it returns nil.

NumberHelper

number_to_human's units also accepts the translation scope of the unit names (such as "number.human.decimal_units.units"). Hash keys must be symbols (:unit, :thousand, etc.); string keys raise an error.
On the Japanese page, number_to_human_size uses Rails' built-in English format, but 1 byte is also Bytes (the English translation gives Byte).
Even for a value that is not a number, number_to_phone adds delimiters if it ends in a run of digits ("tel 5551234" gives tel 555-1234).

SanitizeHelper

Because this site uses load_defaults 8.1, sanitize, strip_tags and strip_links use the HTML5 sanitizer (config.action_view.sanitizer_vendor). The HTML4 sanitizer behaves differently; for example, its strip_tags also removes the content of <script>.
sanitize's scrubber also accepts a Loofah scrubber name (such as :prune).

token_list

Escapes the tokens. Strings that are already escaped, such as &, are unescaped once before escaping, so they are not escaped twice. Unlike other helpers, it also escapes strings marked html_safe.
Unlike passing an array or a hash to class in other helpers (tag.div(class: ["btn", {active: true}])), splits strings at spaces and merges duplicate tokens.

javascript_tag

With a block, uses the block's output as the content. In that case, a hash as the first argument becomes html_options (a string is ignored). The page does not cover the block form.
A ]]> in the content is split into ]]]]><![CDATA[> so that the CDATA section does not end early.

collection_checkboxes

The :readonly option, like :disabled, accepts a value, an array of values or a proc. It adds readonly to the matching checkboxes, but per the HTML spec, a readonly checkbox can still be checked and unchecked.
Passing id in html_options gives every checkbox's id and every <label>'s for the same value.
Passing disabled: true in html_options does not add it to the hidden <input> at the top, so an empty value is still sent.
Passing index in html_options puts the index in the checkboxes' name, but not in the name of the hidden <input> at the top. Passing it in options does the opposite: only the hidden <input> gets it.
b.checkbox and b.label in the block take a hash of HTML attributes (keys also in html_options get the html_options value). The same goes for b.radio_button in collection_radio_buttons.

collection_radio_buttons

Passing an array to the :checked option adds checked to every matching radio button (two for checked: [1, 2]).
The :readonly option, and id, disabled and index in html_options, are the same as in collection_checkboxes. A radio button can still be selected even with readonly.

collection_select

If value_method is a proc, also passing a proc to the :selected or :disabled option raises TypeError where that proc returns true.
If an item of collection is an array, a hash in it becomes HTML attributes of that item's <option> ([[1, "A", { class: "x" }]] with :first and :second). The same goes for collection_checkboxes, collection_radio_buttons and options_from_collection_for_select, and it takes precedence over the same keys in html_options.

grouped_collection_select

If option_key_method is a proc, also passing a proc to the :selected or :disabled option raises TypeError where that proc returns true. Same as collection_select.

grouped_options_for_select

Passing a hash together with divider also lists the group names (the keys) as ordinary <option> elements.
Passing an array that is not in the grouped format (%w[basic pro]) raises NoMethodError.

fields_for

In FormBuilder's f.fields_for, a record_name in the "comments[]" format uses the id of record_object as the index, as in article[comments][1][body].
record_name also accepts an object instead of a symbol (fields_for @comment). This is the same as using the model name (comment) as the prefix of the name and id and passing the object as record_object.
FormHelper's fields_for does not treat a hash passed as record_object as options (FormBuilder's f.fields_for does). fields_for :comment, index: 1 uses the hash as the object, so fields such as c.text_field :body raise NoMethodError when they read the value. When record_name is an object (fields_for @comment, index: 1), the hash is not used, so neither are the options. To pass options as well, pass nil as record_object, as in fields_for :comment, nil, index: 1.
If FormBuilder's f.fields_for gets no include_id, it uses the include_id given to the outer form (form_with, or the outer f.fields_for when nested). The form_with page does not list this option, but when it is passed as in form_with(model: @article, include_id: false), the inner f.fields_for uses that value. Passing skip_id: true to form_with or f.fields is the same as include_id: false (passing it to f.fields_for has no effect).

fields

fields is a version of fields_for that is called the same way as form_with (fields(:author, model: @author)). The only differences are that allow_method_names_outside_object defaults to true, and that config.action_view.form_with_generates_ids decides the id of the elements created in the block. It was added in Rails 5.1, alongside form_with, to replace fields_for, but it never did, and both remain. It behaves much like fields_for, and as far as a GitHub search shows, real apps rarely use it, so there is no page for fields.

f.button

If scope or as is given to the outer form, that value becomes the prefix of the name and id when the value argument is a symbol (post[draft]). The translation key for the content also changes: it looks up helpers.submit.post.create instead of helpers.submit.article.create. namespace is prepended only to the id built from the symbol.
If the outer form has no object (such as form_with(url: "/search")), it looks up the helpers.submit.submit translation for the content and appends the scope name, as in Save Post with Rails' English translations, or Submit Post without a translation. Without scope either, a trailing space is left after Save.
Whether formmethod is rewritten depends on whether the value contains post or get, so a value such as "postx" is not rewritten.

f.submit

A symbol passed as the value argument is only converted to a string and used as the value attribute (f.submit :draft gives value="draft"). Unlike f.button, does not create a name or id.
Passing :value overrides the value attribute, but data-disable-with stays the string of the first argument, value (f.submit "Save", value: "Other" gives value="Other" data-disable-with="Save").
Passing formmethod: :delete adds formmethod="delete" as is. Unlike f.button, does not rewrite it into _method.
Setting config.action_view.automatically_disable_submit_tag to false stops it from adding data-disable-with. The setting defaults to true.
A block is ignored without raising an error.
As with f.button, if the enclosing form is given scope or as, the translation is looked up under that name (helpers.submit.post.create).
data: { disable_with: false } adds no data-disable-with. If "data-disable-with" is also given in options, that one is used.
The type option changes type="submit" (such as type: "button").

field_id, field_name

Passing field_id an object_name ending in [], such as "article[comments][]", gives two _ in a row: article_comments__title.
Unlike field_id, field_name uses the object's to_s as the prefix when given a model object (#<Article:0x…>[tags]).

file_field

The hidden <input> from include_hidden sends an empty value to Active Storage's has_many_attached so that all attachments can be removed. Sending the edit form without choosing a file removes the current attachments.
The hidden <input> from include_hidden gets only name; unlike in checkbox, it does not get disabled or form. So even when the file <input> has the disabled attribute, the hidden <input>'s empty value is sent and the current attachments are removed.
Called as f.file_field on a form builder, it adds enctype="multipart/form-data" to the enclosing form_with or form_for (also inside a nested f.fields_for). Calling file_field directly does not.

rich_textarea

< and > in the block's content are not escaped when it goes into the value of the hidden <input>. If the :value option is given or the object has a value, the block is ignored.
Even when disabled, Trix accepts dropped and pasted files (Trix also makes the hidden <input> disabled, so they are not sent).

options_for_select

Passing a proc as the selected argument does not add selected to any <option>; unlike collection_select, it does not call the proc.
Passing the grouped format ({ "Free" => ["basic"] }) as container creates an <option> with value="["basic"]" instead of an <optgroup>. For groups, use grouped_options_for_select.
A string passed as container is returned as is.

options_from_collection_for_select

If value_method is a proc, also passing a proc as the selected argument (or in a hash with the keys selected and disabled) raises TypeError where that proc returns true. Same as collection_select.

option_groups_from_collection_for_select

If option_key_method is a proc, also passing a proc as selected_key (or in a hash with the keys selected and disabled) raises TypeError where that proc returns true. Same as grouped_collection_select.

search_field

Older versions of Safari supported the HTML attributes autosave (the name under which recent searches are saved) and results (how many recent searches to list). Passing autosave also adds results="10" if there is no results. Testing in Safari on macOS did not reveal what they do, and no information could be found, so the page leaves them out. Passing autosave: true, which should use the host name reversed as the value, raises NameError (Tags::SearchField in Rails 8.1.4.1 has no request).

select

With a block, uses the block's output as the content of the <select> instead of choices, and choices can be omitted (select(:user, :plan) do … end).
choices also accepts a range (with 1..3, the text and value are 1, 2 and 3).
required in html_options adds an empty <option> only when there is no multiple and size is 1.
Passing both the :prompt and :include_blank options adds both <option> elements. Passing disabled: "" or selected: "" along with them adds disabled or selected to the prompt <option>.
With multiple: true, disabled in html_options is also added to the hidden <input> at the top. The same goes for collection_select and grouped_collection_select.

select_tag

Unlike select, passing required in options does not add an empty <option>, and passing multiple: true does not add a hidden <input> with an empty value.
Appends [] to the name only when multiple is true. multiple: "multiple" adds the multiple attribute but not [].
Passing both prompt and include_blank adds both, with the prompt <option> first.

form_with

Without a block, outputs only the opening <form> tag and the hidden <input> elements, without </form>. You write the content and </form> yourself.
authenticity_token also accepts a string, which is used as is for the value of the hidden <input> that holds the CSRF token.
local defaults to true, and data-remote="true" is not added, because config.action_view.form_with_generates_remote_forms is false (load_defaults 6.1 and later).
skip_enforcing_utf8: false or enforce_utf8: true adds a hidden <input> with name="utf8" (whose value is ✓), which makes old browsers send the form in UTF-8. If neither is given, it is not added, because config.action_view.default_enforce_utf8 is false (load_defaults 6.0 and later).

time_zone_select

Passing a class that responds to all to the :model option uses the list from that class's all instead of ActiveSupport::TimeZone.
The third argument of time_zone_options_for_select, model, works like the :model option of time_zone_select.
Passing an array of name strings (["Tokyo"]) to priority_zones raises NoMethodError. Pass ActiveSupport::TimeZone objects or a regular expression. The same goes for time_zone_options_for_select.
The object's value and default are compared as name strings ("Tokyo"). An ActiveSupport::TimeZone object selects nothing.

textarea

Adds a newline before the content. In HTML, a newline right after <textarea> is ignored, so this keeps the newline when the content starts with one (such as text whose first line is empty). If the content does not start with a newline, the added one is ignored and nothing changes.

weekday_select

Day names come from the date.day_names translation. Rails ships only English translations, so in other locales it raises NoMethodError unless you provide translations, such as those from rails-i18n.
Added in Rails 7.0.
A block is accepted but ignored. It does not raise an error either.