skip to content

In Rails, what does the field_with_errors wrapper do to a form with invalid fields, and how do you change it with field_error_proc?

level: middleimportance: should knowfreq 40%

answer

  1. ActionView::Base.field_error_proc
  2. <div class="field_with_errors">
  3. label and input wrapped separately
  4. hidden fields are skipped
  5. config.action_view.field_error_proc

basics

~10 s

When a field's attribute has errors, Rails passes the field's HTML through field_error_proc, which by default wraps it in <div class="field_with_errors">. Set config.action_view.field_error_proc to a different proc to change or remove that wrapper app-wide.

solid answer

~40 s

Form helpers bound to a model check `object.errors[method]` while rendering; if it is non-empty they hand the generated tag to `ActionView::Base.field_error_proc`. The default proc returns `content_tag :div, html_tag, class: "field_with_errors"`. It applies to the label and the input separately, and to selects and text areas, but not to hidden fields. A block-level `div` around inline elements often breaks layouts: flex and grid rows, inline labels, and CSS such as `input + label`. Fixes range from CSS, `.field_with_errors { display: contents; }`, to replacing the proc in `config/application.rb` with `config.action_view.field_error_proc = proc { |html_tag, instance| html_tag }` and marking invalid inputs with `aria-invalid` instead. The proc runs inside the view, so helpers work, and `instance.error_message` gives that field's messages. It is global, so per-form styling belongs in a custom form builder.

code

ruby · 9 lines
ruby
# config/application.rb
module VolunteerHub
  class Application < Rails::Application
    config.load_defaults 8.1

    # Leave invalid fields unwrapped; views set aria-invalid and print messages.
    config.action_view.field_error_proc = proc { |html_tag, _instance| html_tag }
  end
end

go deeper

for a junior

Recall that invalid fields come back wrapped in a div with class field_with_errors, which you can style with CSS.

for a middle

Explain that the wrapper comes from ActionView::Base.field_error_proc, which elements it wraps, and how config.action_view.field_error_proc replaces it.

for a senior

Choose between CSS, a neutral proc with aria-invalid, or a custom builder, and remember the proc is global and receives labels as well as inputs.

for a principal

Align the wrapper behaviour with the design system once, so every form, including engines, renders invalid fields the same accessible way.

## Where the wrapper comes from Every model-bound field helper, such as `form.text_field :email` or `form.label :email`, is rendered by an Action View tag class. Before returning its HTML, that class asks the bound object for `errors[:email]`. When the list is not empty, it calls: ```ruby # inside Action View's tag classes (simplified) @template_object.instance_exec(html_tag, self, &ActionView::Base.field_error_proc) ``` The default value is: ```ruby Proc.new { |html_tag, instance| content_tag :div, html_tag, class: "field_with_errors" } ``` So a rejected volunteer email renders as: ```html <div class="field_with_errors"><label for="volunteer_email">Email</label></div> <div class="field_with_errors"><input type="email" name="volunteer[email]" id="volunteer_email" value="bob@"></div> ``` ## What gets wrapped | Output | Wrapped? | |---|---| | `label`, `text_field`, `email_field`, `textarea` | yes, each in its own div | | `select`, `collection_select` | the `<select>`, not its `<option>`s | | `checkbox` | the visible box; its hidden `0` input is not | | `hidden_field` | never | | fields whose attribute has no errors | never | The lookup is by the helper's method name, so an error stored under a different key from the field, such as `:team` for a `team_id` select, does not trigger it. ## Why teams change it - **Layout breakage.** A `div` is block-level. Inline label-input pairs, flex rows and grid cells gain an extra box and shift when validation fails. - **Selector breakage.** CSS like `input:checked + label` stops matching once each element sits in its own wrapper. - **Design systems.** Frameworks style invalid inputs with a class or with `aria-invalid`, not with a wrapper. ## Ways to change it 1. **CSS only.** `.field_with_errors { display: contents; }` removes the wrapper's box from layout while keeping the class for styling the children. 2. **Return the tag untouched.** `config.action_view.field_error_proc = proc { |html_tag, _instance| html_tag }` in `config/application.rb`, then mark invalid inputs yourself, for example with `aria: { invalid: true }` when the attribute has errors. 3. **Append the message.** The proc runs through `instance_exec` in the view, so helpers are available, and `instance.error_message` returns the field's messages. Because the proc also receives labels, guard on the tag before appending: ```ruby config.action_view.field_error_proc = proc do |html_tag, instance| if html_tag.start_with?("<label") html_tag else html_tag + tag.span(instance.error_message.to_sentence, class: "field-error") end end ``` 4. **Per-form control.** The proc is a single global setting, applied to every form in the app, including engines'. For behaviour that differs between forms, a custom `FormBuilder` is the right tool (that belongs to the form-targets leaf). ## Custom builders still get the wrapper The wrapping happens in Action View's tag classes, below the form builder. A `FormBuilder` subclass that only adds methods, set through `builder:` or `config.action_view.default_form_builder`, still produces wrapped fields, because its `text_field` ends up in the same tag class. To avoid the wrapper inside a builder you either change the proc or have the builder render its fields differently on purpose. ## Things to keep in mind - The proc's result is inserted as HTML, so build it from helpers or from the already-safe `html_tag`; do not interpolate user input into a raw string. - The `html_tag` string is the complete element, so string surgery on it is fragile; prefer wrapping, appending or returning it unchanged. - Setting the proc in `config/application.rb` takes effect at boot; Rails copies `config.action_view` options onto `ActionView::Base` once Action View loads. ## Interview summary `field_with_errors` comes from `field_error_proc`, which wraps each model-bound field and label whose attribute has errors in a `div`. Change it globally with `config.action_view.field_error_proc`, neutralise it with CSS, or move error presentation into a form builder.

  • Why does a rejected form show two red boxes for one field?
    The label and the input are rendered by separate helpers, and each checks the attribute's errors, so each gets its own `field_with_errors` div. Styling should target the input inside the wrapper, or the proc should leave labels alone.
  • Can you turn the wrapper off for just one form?
    Not through `field_error_proc`, which is global. Use CSS scoped to that form, such as `display: contents` on its wrappers, or a custom form builder for that form that renders fields the way it needs.

  • field_with_errors wraps the whole form when any field is invalid.
  • Swapping default_form_builder for a FormBuilder subclass removes the field_with_errors wrapper.
  • The default wrapper is a span, so it never affects layout.
  • Hidden fields are wrapped too, so they show the error styling.
  • field_error_proc adds the error messages next to the input by default.