skip to content

Why does Rails' f.checkbox render a hidden input with value 0 before the checkbox, and how do you change or remove it?

level: middleimportance: must knowfreq 65%

answer

  1. unchecked boxes send nothing
  2. same name, hidden first
  3. the last value wins in params
  4. checked_value "1", unchecked_value "0"
  5. include_hidden: false or nil unchecked

basics

~20 s

Browsers omit unchecked checkboxes, so Rails writes a hidden input with the same name and value 0 first; when checked, the later 1 replaces it in params. Change it through checked and unchecked value arguments; remove it with include_hidden: false.

solid answer

~50 s

A browser submits a checkbox only when it is checked, so without help an unticked newsletter box would send nothing and `update` could never turn the attribute off. `f.checkbox :newsletter` therefore writes `<input type="hidden" name="registration[newsletter]" value="0">` and then the checkbox with `value="1"`. Rails' parser keeps the last value for a repeated plain key, so params get `"1"` when ticked and `"0"` otherwise, and Active Record casts either to a boolean. The signature is `checkbox(method, options = {}, checked_value = "1", unchecked_value = "0")`: pass `"yes", "no"` for other values, `include_hidden: false` to drop the hidden input, or `nil` as the unchecked value. For a set of values, `multiple: true` names the box `registration[dietary_needs][]`; pass `nil` there, or every box adds a `"0"` to the array. In Rails 8, `checkbox` is the primary name and `check_box` an alias.

code

erb · 7 lines
erb
<%= form_with model: @registration do |f| %>
  <%= f.checkbox :newsletter %>
  <%= f.label :newsletter, "Send me conference news" %>

  <%= f.checkbox :photo_consent, {}, "yes", "no" %>
  <%= f.label :photo_consent %>
<% end %>

go deeper

for a junior

Recall the reason: unchecked boxes are not submitted, so Rails adds a hidden 0 with the same name to let an edit turn the value off.

for a middle

Explain the ordering and last-value-wins parsing, the four-argument signature, include_hidden: false, and why multiple: true needs nil as the unchecked value.

for a senior

Diagnose the failure modes: a flag that never turns off after removing the hidden input, zeros polluting array attributes, and ghost rows in unindexed array names.

for a principal

Decide when boolean flags belong in forms at all versus explicit actions, and how to keep array-valued attributes clean across many forms.

## The browser behaviour Rails works around An HTML checkbox is a **successful control** only when it is checked: the browser includes its name and value in the submission when ticked and leaves it out entirely when not. For a create form that is harmless, but for an edit form it breaks the obvious flow. A registration with `newsletter: true` whose box the attendee unticks would submit no `newsletter` key at all, and `@registration.update(registration_params)` would leave the attribute `true`. ## What `f.checkbox` writes `f.checkbox :newsletter` renders two inputs with the **same name**, hidden one first: ```html <input name="registration[newsletter]" type="hidden" value="0"> <input type="checkbox" value="1" name="registration[newsletter]" id="registration_newsletter"> ``` - **Unticked**: only the hidden input is submitted, so params carry `"0"`. - **Ticked**: both are submitted in document order, `0` then `1`. For a plain key that appears twice, Rails' parameter builder (`ActionDispatch::ParamBuilder` in 8.1) assigns each value in turn, so the last one, `"1"`, is what `params[:registration][:newsletter]` holds. Active Record's boolean type casts `"1"` to `true` and `"0"` to `false`, so the column ends up correct either way. The checkbox is pre-ticked when the record's current value matches the checked value; for a boolean, `true` matches `"1"`. ## Changing the values The full signature is `checkbox(method, options = {}, checked_value = "1", unchecked_value = "0")`: - `f.checkbox :photo_consent, {}, "yes", "no"` sends `"yes"` or `"no"` for a string column. - `f.checkbox :newsletter, include_hidden: false` drops the hidden input; an unticked box then sends nothing. - Passing `nil` as `unchecked_value` also drops it. - A `disabled: true` option is copied onto the hidden input too, so a disabled box sends neither value. ## Checkbox groups for array values A dietary-needs section might store several values in one array attribute. `multiple: true` changes the name to end in `[]` and appends the value to the id: ```erb <% %w[vegetarian vegan gluten_free].each do |need| %> <%= f.checkbox :dietary_needs, { multiple: true }, need, nil %> <%= f.label :dietary_needs, need.humanize, value: need %> <% end %> ``` The `nil` matters. With the default unchecked value, every box, ticked or not, would also submit its hidden `"0"` under `registration[dietary_needs][]`, so ticking only vegan would send `["0", "0", "vegan", "0"]`. The label's `value:` option makes its `for` match the per-value id, such as `registration_dietary_needs_vegan`. For a list built from records, `collection_checkboxes` renders the whole group and adds a single hidden empty value instead. ## How the model reads the values Active Model's boolean type casts by a fixed list: `"0"`, `"f"`, `"false"` and `"off"` (in either case) become `false`, an empty string becomes `nil`, and anything else becomes `true`. That is why the defaults suit boolean columns. It also explains a trap with custom values: 1. `f.checkbox :photo_consent, {}, "yes", "no"` on a **string** column stores `"yes"` or `"no"` as written. 2. The same call on a **boolean** column stores `true` for both, because `"no"` is not in the false list. 3. Keep `"1"`/`"0"` for booleans, or pick values the type understands, such as `"true"` and `"false"`. ## When the hidden input hurts The last-value-wins trick depends on the name being a plain key. Inside rows whose names end in `[]` without an index, the repeated hidden value starts a new array element, producing ghost rows; the Rails documentation recommends hash-style names with explicit keys, or `checkbox_tag`, there. `checkbox_tag`, the model-less version, never writes a hidden input. ## Names in Rails 8 | Rails 8 primary name | Alias kept | |---|---| | `checkbox` | `check_box` | | `checkbox_tag` | `check_box_tag` | | `collection_checkboxes` | `collection_check_boxes` | Both spellings behave identically in 8.1.

  • Why does a ticked box not send both 0 and 1 to the model?
    It sends both on the wire, hidden first. For a plain key without `[]`, Rails' parameter builder assigns each occurrence to the same hash key, so the later `"1"` overwrites the `"0"` and the controller sees one value. That ordering is why the hidden input must come before the checkbox.
  • A checkbox group stores ["0", "0", "vegan", "0"]. What went wrong?
    The boxes use `multiple: true` but kept the default unchecked value, so every box, ticked or not, submitted its hidden `"0"` into the same `[]` array. Pass `nil` as the fourth argument so no hidden input is written, or render the group with `collection_checkboxes`, which adds one hidden empty value.

  • Browsers send unchecked checkboxes with an empty value.
  • Rails puts the hidden input after the checkbox so that it wins.
  • params[:registration][:newsletter] arrives as an array ["0", "1"] when ticked.
  • checkbox_tag adds the same hidden 0 as the builder's checkbox.
  • check_box no longer works in Rails 8 and must be renamed.

Assumes Rails 8.1, where checkbox, checkbox_tag and collection_checkboxes are the primary names and the check_box spellings are aliases.