bootstrap_form 5.2.3 → 5.3.0

data/README.md

@@ -19,14 +19,14 @@ Some other nice things that `bootstrap_form` does for you are:
 * Reduces errors, because you're doing less typing.
 * Makes it easier to see the logic of the form, because it's not mixed in with the Bootstrap mark-up.
 
-`bootstrap_form` works like the standard Rails form helpers, and this README assumes you know how they work. You start a form with one of [`bootstrap_form_with`](#bootstrap-form-with), [`bootstrap_form_for`](#bootstrap-form-for), or [`bootstrap_form_tag`](#bootstrap-form-tag) in a view file. You get a form builder that calls the [`bootstrap_form` helpers](#form-helpers) instead of the standard Rails helpers. You use that form builder in the view file to render one or more form fields.
+`bootstrap_form` works like the standard Rails form helpers, and this README assumes you know how they work. You start a form with one of [`bootstrap_form_with`](#bootstrap_form_with), [`bootstrap_form_for`](#bootstrap_form_for), or [`bootstrap_form_tag`](#bootstrap_form_tag) in a view file. You get a form builder that calls the [`bootstrap_form` helpers](#form-helpers) instead of the standard Rails helpers. You use that form builder in the view file to render one or more form fields.
 
 ## Requirements
 
 `bootstrap_form` supports at a minimum the currently supported versions of Ruby and Rails:
 
 * Ruby 3.0+ (https://www.ruby-lang.org/en/downloads/branches/)
-* Rails 6.0+ (https://guides.rubyonrails.org/maintenance_policy.html)
+* Rails 6.1+ (https://guides.rubyonrails.org/maintenance_policy.html)
 * Bootstrap 5.0+
 
 ## Installation
@@ -42,7 +42,7 @@ And follow the remaining instructions in the [official bootstrap installation gu
 Add the `bootstrap_form` gem to your `Gemfile`:
 
 ```ruby
-gem "bootstrap_form", "~> 5.2"
+gem "bootstrap_form", "~> 5.3"
 ```
 
 Then:
@@ -84,7 +84,7 @@ This generates the following HTML:
 <form accept-charset="UTF-8" action="/users" class="new_user" id="new_user" method="post">
   <div class="mb-3">
     <label class="form-label required" for="user_email">Email</label>
-    <input aria-required="true" class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
+    <input class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
   </div>
   <div class="mb-3">
     <label class="form-label" for="user_password">Password</label>
@@ -143,7 +143,7 @@ This generates:
 <form accept-charset="UTF-8" action="/users" method="post">
   <div class="mb-3">
     <label class="form-label required" for="user_email">Email</label>
-    <input aria-required="true" class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
+    <input class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
   </div>
   <div class="mb-3">
     <label class="form-label" for="user_password">Password</label>
@@ -164,6 +164,45 @@ in `form_with`.
 
 `form_with` has some important differences compared to `form_for` and `form_tag`, and these differences apply to `bootstrap_form_with`. A good summary of the differences can be found at: https://m.patrikonrails.com/rails-5-1s-form-with-vs-old-form-helpers-3a5f72a8c78a, or in the [Rails documentation](api.rubyonrails.org).
 
+### bootstrap_fields_for and bootstrap_fields
+
+Adding fields for a different object without nesting can be achieved using the `bootstrap_fields_for` and
+`bootstrap_fields` helpers in the same way it is done in Rails.
+
+![Example 3](demo/doc/screenshots/bootstrap/readme/03_example.png "Example 3")
+```erb
+<%= bootstrap_form_with model: @user do |f| %>
+  <%= f.email_field :email %>
+  <%= bootstrap_fields_for :parent do |pf| %>
+    <%= pf.email_field :email, label: 'Parent email' %>
+  <% end %>
+  <%= bootstrap_fields @user.address do |af| %>
+    <%= af.text_field :street_name %>
+  <% end %>
+  <%= f.primary "Save" %>
+<% end %>
+```
+
+Generated HTML:
+
+```html
+<form accept-charset="UTF-8" action="/users" method="post">
+  <div class="mb-3">
+    <label class="form-label required" for="user_email">Email</label>
+    <input class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
+  </div>
+  <div class="mb-3">
+    <label class="form-label" for="parent_email">Parent email</label>
+    <input class="form-control" id="parent_email" name="parent[email]" type="email">
+  </div>
+  <div class="mb-3">
+    <label class="form-label" for="street_name">Street name</label>
+    <input class="form-control" id="street_name" name="street_name" type="text">
+  </div>
+  <input class="btn btn-primary" data-disable-with="Save" name="commit" type="submit" value="Save">
+</form>
+```
+
 ## Configuration
 
 `bootstrap_form` can be used out-of-the-box without any configuration. However, `bootstrap_form` does have an optional configuration file at `config/initializers/bootstrap_form.rb` for setting options that affect all generated forms in an application.
@@ -232,7 +271,7 @@ The options for the form helpers that aren't in the exceptions list are describe
 
 Use the `label` option if you want to specify the field's label text:
 
-![Example 3](demo/doc/screenshots/bootstrap/readme/03_example.png "Example 3")
+![Example 4](demo/doc/screenshots/bootstrap/readme/04_example.png "Example 4")
 ```erb
 <%= f.password_field :password_confirmation, label: "Confirm Password" %>
 ```
@@ -249,7 +288,7 @@ This generates:
 To hide a label, use the `hide_label: true` option. This adds the `visually-hidden`
 class, which keeps your labels accessible to those using screen readers.
 
-![Example 4](demo/doc/screenshots/bootstrap/readme/04_example.png "Example 4")
+![Example 5](demo/doc/screenshots/bootstrap/readme/05_example.png "Example 5")
 ```erb
 <%= f.text_area :comment, hide_label: true, placeholder: "Leave a comment..." %>
 ```
@@ -258,7 +297,7 @@ This generates:
 
 ```html
 <div class="mb-3">
-  <label class="form-label visually-hidden" for="user_comment">Comment</label>
+  <label class="visually-hidden" for="user_comment">Comment</label>
   <textarea class="form-control" id="user_comment" name="user[comment]" placeholder="Leave a comment...">
 </textarea>
 </div>
@@ -266,33 +305,33 @@ This generates:
 
 To add custom classes to the field's label:
 
-![Example 5](demo/doc/screenshots/bootstrap/readme/05_example.png "Example 5")
+![Example 6](demo/doc/screenshots/bootstrap/readme/06_example.png "Example 6")
 ```erb
-<%= f.text_field :email, label_class: "custom-class" %>
+<%= f.email_field :email, label_class: "custom-class" %>
 ```
 
 This generates:
 
 ```html
 <div class="mb-3">
-  <label class="form-label custom-class required" for="user_email">Email</label>
-  <input aria-required="true" class="form-control" id="user_email" name="user[email]" required="required" type="text" value="steve@example.com">
+  <label class="custom-class required" for="user_email">Email</label>
+  <input class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
 </div>
 ```
 
 Or you can add the label as input placeholder instead (this automatically hides the label):
 
-![Example 6](demo/doc/screenshots/bootstrap/readme/06_example.png "Example 6")
+![Example 7](demo/doc/screenshots/bootstrap/readme/07_example.png "Example 7")
 ```erb
-<%= f.text_field :email, value: '', label_as_placeholder: true %>
+<%= f.email_field :email, value: '', label_as_placeholder: true %>
 ```
 
 This generates:
 
 ```html
 <div class="mb-3">
-  <label class="form-label visually-hidden required" for="user_email">Email</label>
-  <input aria-required="true" class="form-control" id="user_email" name="user[email]" placeholder="Email" required="required" type="text" value="">
+  <label class="visually-hidden required" for="user_email">Email</label>
+  <input class="form-control" id="user_email" name="user[email]" placeholder="Email" required="required" type="email" value="">
 </div>
 ```
 
@@ -300,7 +339,7 @@ This generates:
 
 To specify the class of the generated input tag, use the `control_class` option:
 
-![Example 7](demo/doc/screenshots/bootstrap/readme/07_example.png "Example 7")
+![Example 8](demo/doc/screenshots/bootstrap/readme/08_example.png "Example 8")
 ```erb
 <%= f.text_field :email, control_class: "custom-class" %>
 ```
@@ -310,7 +349,7 @@ This generates:
 ```html
 <div class="mb-3">
   <label class="form-label required" for="user_email">Email</label>
-  <input aria-required="true" class="custom-class" id="user_email" name="user[email]" required="required" type="text" value="steve@example.com">
+  <input class="custom-class" id="user_email" name="user[email]" required="required" type="text" value="steve@example.com">
 </div>
 ```
 
@@ -318,7 +357,7 @@ This generates:
 
 To add help text, use the `help` option:
 
-![Example 8](demo/doc/screenshots/bootstrap/readme/08_example.png "Example 8")
+![Example 9](demo/doc/screenshots/bootstrap/readme/09_example.png "Example 9")
 ```erb
 <%= f.password_field :password, help: "Must be at least 6 characters long" %>
 ```
@@ -363,7 +402,7 @@ option or turn them off completely by passing `help: false`.
 
 You can pass `prepend` and/or `append` options to input fields:
 
-![Example 9](demo/doc/screenshots/bootstrap/readme/09_example.png "Example 9")
+![Example 10](demo/doc/screenshots/bootstrap/readme/10_example.png "Example 10")
 ```erb
 <%= f.text_field :price, prepend: "$", append: ".00" %>
 ```
@@ -383,9 +422,10 @@ This generates:
 
 If you want to attach multiple items to the input, pass them as an array:
 
-![Example 10](demo/doc/screenshots/bootstrap/readme/10_example.png "Example 10")
+![Example 11](demo/doc/screenshots/bootstrap/readme/11_example.png "Example 11")
 ```erb
-<%= f.text_field :price, prepend: ['Net', '$'], append: ['.00', 'per day'] %>
+<% icon = capture do %><i class="bi bi-currency-dollar"></i><% end %>
+<%= f.text_field :price, prepend: ['Net', icon], append: ['.00', 'per day'] %>
 ```
 
 This generates:
@@ -395,7 +435,10 @@ This generates:
   <label class="form-label" for="user_price">Price</label>
   <div class="input-group">
     <span class="input-group-text">Net</span>
-    <span class="input-group-text">$</span>
+    <span class="input-group-text">
+      <i class="bi bi-currency-dollar">
+      </i>
+    </span>
     <input class="form-control" id="user_price" name="user[price]" type="text">
     <span class="input-group-text">.00</span>
     <span class="input-group-text">per day</span>
@@ -406,7 +449,7 @@ This generates:
 You can also prepend and append buttons. Note: The buttons must contain the
 `btn` class to generate the correct markup.
 
-![Example 11](demo/doc/screenshots/bootstrap/readme/11_example.png "Example 11")
+![Example 12](demo/doc/screenshots/bootstrap/readme/12_example.png "Example 12")
 ```erb
 <%= f.text_field :search, append: link_to("Go", "#", class: "btn btn-secondary") %>
 ```
@@ -425,7 +468,7 @@ This generates:
 
 To add a class to the input group wrapper, use the `:input_group_class` option.
 
-![Example 12](demo/doc/screenshots/bootstrap/readme/12_example.png "Example 12")
+![Example 13](demo/doc/screenshots/bootstrap/readme/13_example.png "Example 13")
 ```erb
 <%= f.email_field :email, append: f.primary('Subscribe'), input_group_class: 'input-group-lg' %>
 ```
@@ -436,7 +479,7 @@ This generates:
 <div class="mb-3">
   <label class="form-label required" for="user_email">Email</label>
   <div class="input-group input-group-lg">
-    <input aria-required="true" class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
+    <input class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
     <input class="btn btn-primary" data-disable-with="Subscribe" name="commit" type="submit" value="Subscribe">
   </div>
 </div>
@@ -448,7 +491,7 @@ Bootstrap mark-up dictates that most input field types have the label and input
 
 If you want to change the CSS class or any other attribute to the form group div, you can use the `wrapper: { class: 'mb-3 additional-class', data: { foo: 'bar' } }` option.
 
-![Example 13](demo/doc/screenshots/bootstrap/readme/13_example.png "Example 13")
+![Example 14](demo/doc/screenshots/bootstrap/readme/14_example.png "Example 14")
 ```erb
 <%= f.text_field :name, wrapper: { class: 'mb-3 has-warning', data: { foo: 'bar' } } %>
 ```
@@ -464,7 +507,7 @@ This generates:
 
 Which produces the following output:
 
-![Example 14](demo/doc/screenshots/bootstrap/readme/14_example.png "Example 14")
+![Example 15](demo/doc/screenshots/bootstrap/readme/15_example.png "Example 15")
 ```erb
 <div class="mb-3 has-warning" data-foo="bar">
   <label class="form-label form-control-label" for="user_name">Id</label>
@@ -490,7 +533,7 @@ If you don't want any class on the form group div, you can set it to `false`: `w
 
 You may want to define your own form group div around a field. To do so, add the option `wrapper: false` to the input field. For example:
 
-![Example 15](demo/doc/screenshots/bootstrap/readme/15_example.png "Example 15")
+![Example 16](demo/doc/screenshots/bootstrap/readme/16_example.png "Example 16")
 ```erb
 <%= f.form_group :user do %>
   <%= f.email_field :email, wrapper: false %>
@@ -501,7 +544,7 @@ Generated HTML:
 
 ```html
 <div class="mb-3">
-  <input aria-required="true" class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
+  <input class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
 </div>
 ```
 
@@ -511,7 +554,7 @@ Note that Bootstrap relies on the form group div to correctly format most fields
 
 Our select helper accepts the same arguments as the [default Rails helper](http://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html#method-i-select). Here's an example of how you pass both options and html_options hashes:
 
-![Example 16](demo/doc/screenshots/bootstrap/readme/16_example.png "Example 16")
+![Example 17](demo/doc/screenshots/bootstrap/readme/17_example.png "Example 17")
 ```erb
 <%= f.select :product, [["Apple", 1], ["Grape", 2]], { label: "Choose your favorite fruit:", wrapper: { class: 'has-warning', data: { foo: 'bar' } } }, { class: "selectpicker" } %>
 ```
@@ -534,7 +577,7 @@ Checkboxes and radios should be placed inside of a `form_group` to render
 properly. The following example ensures that the entire form group will display
 an error if an associated validations fails:
 
-![Example 17](demo/doc/screenshots/bootstrap/readme/17_example.png "Example 17")
+![Example 18](demo/doc/screenshots/bootstrap/readme/18_example.png "Example 18")
 ```erb
 <%= f.form_group :skill_level, label: { text: "Skill" }, help: "Optional Help Text" do %>
   <%= f.radio_button :skill_level, 0, label: "Novice", checked: true %>
@@ -577,7 +620,7 @@ This generates:
 
 You can also create a checkbox using a block:
 
-![Example 18](demo/doc/screenshots/bootstrap/readme/18_example.png "Example 18")
+![Example 19](demo/doc/screenshots/bootstrap/readme/19_example.png "Example 19")
 ```erb
 <%= f.form_group :terms, label: { text: "Optional Label" } do %>
   <%= f.check_box :terms do %>
@@ -603,7 +646,7 @@ This generates:
 
 To display checkboxes and radios inline, pass the `inline: true` option:
 
-![Example 19](demo/doc/screenshots/bootstrap/readme/19_example.png "Example 19")
+![Example 20](demo/doc/screenshots/bootstrap/readme/20_example.png "Example 20")
 ```erb
 <%= f.form_group :skill_level, label: { text: "Skill" } do %>
   <%= f.radio_button :skill_level, 0, label: "Novice", inline: true %>
@@ -634,7 +677,7 @@ This generates:
 
 Check boxes and radio buttons are wrapped in a `div.form-check`. You can add classes to this `div` with the `:wrapper_class` option:
 
-![Example 20](demo/doc/screenshots/bootstrap/readme/20_example.png "Example 20")
+![Example 21](demo/doc/screenshots/bootstrap/readme/21_example.png "Example 21")
 ```erb
 <%= f.radio_button :skill_level, 0, label: "Novice", inline: true, wrapper_class: "w-auto" %>
 ```
@@ -650,7 +693,7 @@ This generates:
 
 You can also add a style to the tag using the `wrapper` option:
 
-![Example 21](demo/doc/screenshots/bootstrap/readme/21_example.png "Example 21")
+![Example 22](demo/doc/screenshots/bootstrap/readme/22_example.png "Example 22")
 ```erb
 <%= f.check_box :skilled, inline: true, wrapper: {style: "color: green"} %>
 <%= f.radio_button :skill_level, 0, label: "Novice", inline: true, wrapper: {class: 'w-auto', style: "color: red"} %>
@@ -674,7 +717,7 @@ This generates:
 
 To render checkboxes as switches with Bootstrap 4.2+, use `switch: true`:
 
-![Example 22](demo/doc/screenshots/bootstrap/readme/22_example.png "Example 22")
+![Example 23](demo/doc/screenshots/bootstrap/readme/23_example.png "Example 23")
 ```erb
 <%= f.check_box :remember_me, switch: true %>
 ```
@@ -694,7 +737,7 @@ This generates:
 `bootstrap_form` also provides helpers that automatically create the
 `form_group` and the `radio_button`s or `check_box`es for you:
 
-![Example 23](demo/doc/screenshots/bootstrap/readme/23_example.png "Example 23")
+![Example 24](demo/doc/screenshots/bootstrap/readme/24_example.png "Example 24")
 ```erb
 <%= f.collection_radio_buttons :skill_level, Skill.all, :id, :name %>
 <%= f.collection_check_boxes :skills, Skill.all, :id, :name %>
@@ -714,7 +757,7 @@ This generates:
     <label class="form-check-label" for="user_skill_level_2">Farming</label>
   </div>
 </div>
-<input autocomplete="off" id="user_skills" multiple name="user[skills][]" type="hidden" value="">
+<input autocomplete="off" id="user_skills" name="user[skills][]" type="hidden" value="">
 <div class="mb-3">
   <label class="form-label" for="user_skills">Skills</label>
   <div class="form-check">
@@ -737,11 +780,38 @@ Collection methods accept these options:
 * `:help`: Add a help span to the `form_group`
 * Other options will be forwarded to the `radio_button`/`check_box` method
 
+
+To add `data-` attributes to a collection of radio buttons, map your models to an array and add a hash:
+
+![Example 25](demo/doc/screenshots/bootstrap/readme/25_example.png "Example 25")
+```erb
+<%# Use the :first and :second elements of the array to be the value and label respectively %>
+<%- choices = @collection.map { |addr| [ addr.id, addr.street, { 'data-zip-code':  addr.zip_code } ] } -%>
+
+<%= f.collection_radio_buttons :misc, choices, :first, :second %>
+```
+
+This generates:
+
+```html
+<div class="mb-3">
+  <label class="form-label" for="user_misc">Misc</label>
+  <div class="form-check">
+    <input class="form-check-input" id="user_misc_1" name="user[misc]" type="radio" value="1">
+    <label class="form-check-label" for="user_misc_1">Foo</label>
+  </div>
+  <div class="form-check">
+    <input class="form-check-input" id="user_misc_2" name="user[misc]" type="radio" value="2">
+    <label class="form-check-label" for="user_misc_2">Bar</label>
+  </div>
+</div>
+```
+
 ## Range Controls
 
 You can create a range control like this:
 
-![Example 24](demo/doc/screenshots/bootstrap/readme/24_example.png "Example 24")
+![Example 26](demo/doc/screenshots/bootstrap/readme/26_example.png "Example 26")
 ```erb
 <%= f.range_field :excellence %>
 ```
@@ -759,7 +829,7 @@ This generates:
 
 You can create a static control like this:
 
-![Example 25](demo/doc/screenshots/bootstrap/readme/25_example.png "Example 25")
+![Example 27](demo/doc/screenshots/bootstrap/readme/27_example.png "Example 27")
 ```erb
 <%= f.static_control :email %>
 ```
@@ -769,13 +839,13 @@ This generates:
 ```html
 <div class="mb-3">
   <label class="form-label required" for="user_email">Email</label>
-  <input aria-required="true" class="form-control-plaintext" id="user_email" name="user[email]" readonly required="required" type="text" value="steve@example.com">
+  <input class="form-control-plaintext" id="user_email" name="user[email]" readonly required="required" type="text" value="steve@example.com">
 </div>
 ```
 
 Here's the output for a horizontal layout:
 
-![Example 26](demo/doc/screenshots/bootstrap/readme/26_example.png "Example 26")
+![Example 28](demo/doc/screenshots/bootstrap/readme/28_example.png "Example 28")
 ```erb
 <%= bootstrap_form_for(@user, layout: :horizontal) do |f| %>
   <%= f.static_control :email %>
@@ -787,9 +857,9 @@ This generates:
 ```html
 <form accept-charset="UTF-8" action="/users" class="new_user" id="new_user" method="post">
   <div class="mb-3 row">
-    <label class="form-label col-form-label col-sm-2 required" for="user_email">Email</label>
+    <label class="col-form-label col-sm-2 required" for="user_email">Email</label>
     <div class="col-sm-10">
-      <input aria-required="true" class="form-control-plaintext" id="user_email" name="user[email]" readonly required="required" type="text" value="steve@example.com">
+      <input class="form-control-plaintext" id="user_email" name="user[email]" readonly required="required" type="text" value="steve@example.com">
     </div>
   </div>
 </form>
@@ -797,7 +867,7 @@ This generates:
 
 You can also create a static control that isn't based on a model attribute:
 
-![Example 27](demo/doc/screenshots/bootstrap/readme/27_example.png "Example 27")
+![Example 29](demo/doc/screenshots/bootstrap/readme/29_example.png "Example 29")
 ```erb
 <%= f.static_control :field_name, label: "Custom Static Control", value: "Content Here" %>
 ```
@@ -815,7 +885,7 @@ This generates:
 
 You can also create the static control the following way, if you don't need to get the value of the static control as a parameter when the form is submitted:
 
-![Example 28](demo/doc/screenshots/bootstrap/readme/28_example.png "Example 28")
+![Example 30](demo/doc/screenshots/bootstrap/readme/30_example.png "Example 30")
 ```erb
 <%= f.static_control label: "Custom Static Control", value: "Content Here", name: nil %>
 ```
@@ -842,14 +912,14 @@ The multiple selects that the date and time helpers (`date_select`,
 `time_select`, `datetime_select`) generate are wrapped inside a
 `div.rails-bootstrap-forms-[date|time|datetime]-select` tag. This is because
 Bootstrap automatically styles our controls as `block`s. This wrapper fixes
-this defining these selects as `inline-block` and a width of `auto`.
+this by defining these selects as `inline-block` and a width of `auto`.
 
 ## Submit Buttons
 
 The `btn btn-secondary` CSS classes are automatically added to your submit
 buttons.
 
-![Example 29](demo/doc/screenshots/bootstrap/readme/29_example.png "Example 29")
+![Example 31](demo/doc/screenshots/bootstrap/readme/31_example.png "Example 31")
 ```erb
 <%= f.submit %>
 ```
@@ -863,7 +933,7 @@ This generates:
 You can also use the `primary` helper, which adds `btn btn-primary` to your
 submit button:
 
-![Example 30](demo/doc/screenshots/bootstrap/readme/30_example.png "Example 30")
+![Example 32](demo/doc/screenshots/bootstrap/readme/32_example.png "Example 32")
 ```erb
 <%= f.primary "Optional Label" %>
 ```
@@ -876,7 +946,7 @@ This generates:
 
 You can specify your own classes like this:
 
-![Example 31](demo/doc/screenshots/bootstrap/readme/31_example.png "Example 31")
+![Example 33](demo/doc/screenshots/bootstrap/readme/33_example.png "Example 33")
 ```erb
 <%= f.submit "Log In", class: "btn btn-success" %>
 ```
@@ -892,23 +962,23 @@ it will be rendered as an HTML button, instead of an input tag. This allows you
 to specify HTML content and styling for your buttons (such as adding
 illustrative icons to them). For example, the following statements
 
-![Example 32](demo/doc/screenshots/bootstrap/readme/32_example.png "Example 32")
+![Example 34](demo/doc/screenshots/bootstrap/readme/34_example.png "Example 34")
 ```erb
-<%= f.primary "Save changes <span class='fa fa-save'></span>".html_safe, render_as_button: true %>
+<%= f.primary "Save changes <span class='bi bi-save'></span>".html_safe, render_as_button: true %>
 
 <%= f.primary do
       concat 'Save changes '
-      concat content_tag(:span, nil, class: 'fa fa-save')
+      concat content_tag(:span, nil, class: 'bi bi-save')
     end %>
 ```
 
 This generates:
 
 ```html
-<button class="btn btn-primary" name="button" type="submit">Save changes <span class="fa fa-save">
+<button class="btn btn-primary" name="button" type="submit">Save changes <span class="bi bi-save">
   </span>
 </button>
-<button class="btn btn-primary" name="button" type="submit">Save changes <span class="fa fa-save">
+<button class="btn btn-primary" name="button" type="submit">Save changes <span class="bi bi-save">
   </span>
 </button>
 ```
@@ -916,7 +986,7 @@ This generates:
 are equivalent, and each of them both be rendered as:
 
 ```html
-<button name="button" type="submit" class="btn btn-primary">Save changes <span class="fa fa-save"></span></button>
+<button name="button" type="submit" class="btn btn-primary">Save changes <span class="bi bi-save"></span></button>
 ```
 
 If you wish to add additional CSS classes to your button, while keeping the
@@ -926,7 +996,7 @@ Bootstrap classes), or for element targeting via CSS classes.
 Be aware, however, that using the `class` option will discard any extra classes
 you add. As an example, the following button declarations
 
-![Example 33](demo/doc/screenshots/bootstrap/readme/33_example.png "Example 33")
+![Example 35](demo/doc/screenshots/bootstrap/readme/35_example.png "Example 35")
 ```erb
 <%= f.primary "My Nice Button", extra_class: 'my-button' %>
 
@@ -944,7 +1014,7 @@ will be rendered as
 
 ## Rich Text Areas AKA Trix Editor
 
-![Example 34](demo/doc/screenshots/bootstrap/readme/34_example.png "Example 34")
+![Example 36](demo/doc/screenshots/bootstrap/readme/36_example.png "Example 36")
 ```erb
 <%= f.rich_text_area(:life_story) %>
 ```
@@ -1012,7 +1082,7 @@ The `hidden_field` helper in `bootstrap_form` calls the Rails helper directly, a
 If you want to use the original Rails form helpers for a particular field,
 append `_without_bootstrap` to the helper:
 
-![Example 35](demo/doc/screenshots/bootstrap/readme/35_example.png "Example 35")
+![Example 37](demo/doc/screenshots/bootstrap/readme/37_example.png "Example 37")
 ```erb
 <%= f.text_field_without_bootstrap :email %>
 ```
@@ -1034,7 +1104,7 @@ To use an inline-layout form, use the `layout: :inline` option. To hide labels,
 use the `hide_label: true` option, which keeps your labels accessible to those
 using screen readers.
 
-![Example 36](demo/doc/screenshots/bootstrap/readme/36_example.png "Example 36")
+![Example 38](demo/doc/screenshots/bootstrap/readme/38_example.png "Example 38")
 ```erb
 <%= bootstrap_form_for(@user, layout: :inline) do |f| %>
   <%= f.email_field :email, hide_label: true %>
@@ -1049,17 +1119,19 @@ This generates:
 ```html
 <form accept-charset="UTF-8" action="/users" class="new_user row row-cols-auto g-3 align-items-center" id="new_user" method="post">
   <div class="col">
-    <label class="form-label visually-hidden me-sm-2 required" for="user_email">Email</label>
-    <input aria-required="true" class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
+    <label class="visually-hidden required" for="user_email">Email</label>
+    <input class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
   </div>
   <div class="col">
-    <label class="form-label visually-hidden me-sm-2" for="user_password">Password</label>
+    <label class="visually-hidden" for="user_password">Password</label>
     <input class="form-control" id="user_password" name="user[password]" type="password">
   </div>
-  <div class="form-check form-check-inline mb-3">
-    <input autocomplete="off" name="user[remember_me]" type="hidden" value="0">
-    <input class="form-check-input" id="user_remember_me" name="user[remember_me]" type="checkbox" value="1">
-    <label class="form-check-label" for="user_remember_me">Remember me</label>
+  <div class="col">
+    <div class="form-check form-check-inline">
+      <input autocomplete="off" name="user[remember_me]" type="hidden" value="0">
+      <input class="form-check-input" id="user_remember_me" name="user[remember_me]" type="checkbox" value="1">
+      <label class="form-check-label" for="user_remember_me">Remember me</label>
+    </div>
   </div>
   <div class="col">
     <input class="btn btn-secondary" data-disable-with="Create User" name="commit" type="submit" value="Create User">
@@ -1069,7 +1141,7 @@ This generates:
 
 To skip label rendering at all, use `skip_label: true` option.
 
-![Example 37](demo/doc/screenshots/bootstrap/readme/37_example.png "Example 37")
+![Example 39](demo/doc/screenshots/bootstrap/readme/39_example.png "Example 39")
 ```erb
 <%= f.password_field :password, skip_label: true %>
 ```
@@ -1088,17 +1160,15 @@ To use a horizontal-layout form with labels to the left of the control, use the
 `layout: :horizontal` option. You should specify both `label_col` and
 `control_col` css classes as well (they default to `col-sm-2` and `col-sm-10`).
 
-In the example below, the checkbox and submit button have been wrapped in a
-`form_group` to keep them properly aligned.
+In the example below, the submit button has been wrapped in a `form_group` to
+keep it properly aligned.
 
-![Example 38](demo/doc/screenshots/bootstrap/readme/38_example.png "Example 38")
+![Example 40](demo/doc/screenshots/bootstrap/readme/40_example.png "Example 40")
 ```erb
 <%= bootstrap_form_for(@user, layout: :horizontal, label_col: "col-sm-2", control_col: "col-sm-10") do |f| %>
   <%= f.email_field :email %>
   <%= f.password_field :password %>
-  <%= f.form_group do %>
-    <%= f.check_box :remember_me %>
-  <% end %>
+  <%= f.check_box :remember_me %>
   <%= f.form_group do %>
     <%= f.submit %>
   <% end %>
@@ -1110,13 +1180,13 @@ This generates:
 ```html
 <form accept-charset="UTF-8" action="/users" class="new_user" id="new_user" method="post">
   <div class="mb-3 row">
-    <label class="form-label col-form-label col-sm-2 required" for="user_email">Email</label>
+    <label class="col-form-label col-sm-2 required" for="user_email">Email</label>
     <div class="col-sm-10">
-      <input aria-required="true" class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
+      <input class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
     </div>
   </div>
   <div class="mb-3 row">
-    <label class="form-label col-form-label col-sm-2" for="user_password">Password</label>
+    <label class="col-form-label col-sm-2" for="user_password">Password</label>
     <div class="col-sm-10">
       <input class="form-control" id="user_password" name="user[password]" type="password">
     </div>
@@ -1140,11 +1210,12 @@ This generates:
 
 The `label_col` and `control_col` css classes can also be changed per control:
 
-![Example 39](demo/doc/screenshots/bootstrap/readme/39_example.png "Example 39")
+![Example 41](demo/doc/screenshots/bootstrap/readme/41_example.png "Example 41")
 ```erb
 <%= bootstrap_form_for(@user, layout: :horizontal) do |f| %>
   <%= f.email_field :email %>
-  <%= f.text_field :age, control_col: "col-sm-3" %>
+  <%= f.text_field :age, label_col: "col-sm-3", control_col: "col-sm-3" %>
+  <%= f.check_box :terms, label_col: "", control_col: "col-sm-11" %>
   <%= f.form_group do %>
     <%= f.submit %>
   <% end %>
@@ -1156,17 +1227,26 @@ This generates:
 ```html
 <form accept-charset="UTF-8" action="/users" class="new_user" id="new_user" method="post">
   <div class="mb-3 row">
-    <label class="form-label col-form-label col-sm-2 required" for="user_email">Email</label>
+    <label class="col-form-label col-sm-2 required" for="user_email">Email</label>
     <div class="col-sm-10">
-      <input aria-required="true" class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
+      <input class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
     </div>
   </div>
   <div class="mb-3 row">
-    <label class="form-label col-form-label col-sm-2" for="user_age">Age</label>
+    <label class="col-form-label col-sm-3" for="user_age">Age</label>
     <div class="col-sm-3">
       <input class="form-control" id="user_age" name="user[age]" type="text" value="42">
     </div>
   </div>
+  <div class="mb-3 row">
+    <div class="col-sm-10">
+      <div class="form-check">
+        <input autocomplete="off" name="user[terms]" type="hidden" value="0">
+        <input class="form-check-input" id="user_terms" name="user[terms]" type="checkbox" value="1">
+        <label class="form-check-label" for="user_terms">Terms</label>
+      </div>
+    </div>
+  </div>
   <div class="mb-3 row">
     <div class="col-sm-10 offset-sm-2">
       <input class="btn btn-secondary" data-disable-with="Create User" name="commit" type="submit" value="Create User">
@@ -1188,7 +1268,7 @@ module BootstrapForm
       'col-sm-8'
     end
     def default_layout
-      # :default, :horizontal or :inline
+      # :vertical, :horizontal or :inline
       :horizontal
     end
   end
@@ -1197,7 +1277,7 @@ end
 
 Control col wrapper class can be modified with `add_control_col_class`. This option will preserve column definition:
 
-![Example 40](demo/doc/screenshots/bootstrap/readme/40_example.png "Example 40")
+![Example 42](demo/doc/screenshots/bootstrap/readme/42_example.png "Example 42")
 ```erb
 <%= bootstrap_form_for(@user, layout: :horizontal) do |f| %>
   <%= f.email_field :email %>
@@ -1213,13 +1293,13 @@ This generates:
 ```html
 <form accept-charset="UTF-8" action="/users" class="new_user" id="new_user" method="post">
   <div class="mb-3 row">
-    <label class="form-label col-form-label col-sm-2 required" for="user_email">Email</label>
+    <label class="col-form-label col-sm-2 required" for="user_email">Email</label>
     <div class="col-sm-10">
-      <input aria-required="true" class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
+      <input class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
     </div>
   </div>
   <div class="mb-3 row">
-    <label class="form-label col-form-label col-sm-2" for="user_age">Age</label>
+    <label class="col-form-label col-sm-2" for="user_age">Age</label>
     <div class="col-sm-10 additional-control-col-class">
       <input class="form-control" id="user_age" name="user[age]" type="text" value="42">
     </div>
@@ -1236,15 +1316,16 @@ This generates:
 
 The form-level `layout` can be overridden per field, unless the form-level layout was `inline`:
 
-![Example 41](demo/doc/screenshots/bootstrap/readme/41_example.png "Example 41")
+![Example 43](demo/doc/screenshots/bootstrap/readme/43_example.png "Example 43")
 ```erb
 <%= bootstrap_form_for(@user, layout: :horizontal) do |f| %>
   <%= f.email_field :email %>
-  <%= f.text_field :feet, layout: :default %>
-  <%= f.text_field :inches, layout: :default %>
-  <%= f.form_group do %>
-    <%= f.submit %>
-  <% end %>
+  <div class="row">
+    <div class="col"><%= f.text_field :feet, layout: :vertical %></div>
+    <div class="col"><%= f.text_field :inches, layout: :vertical %></div>
+  </div>
+  <%= f.check_box :terms, layout: :vertical %>
+  <%= f.submit %>
 <% end %>
 ```
 
@@ -1253,70 +1334,44 @@ This generates:
 ```html
 <form accept-charset="UTF-8" action="/users" class="new_user" id="new_user" method="post">
   <div class="mb-3 row">
-    <label class="form-label col-form-label col-sm-2 required" for="user_email">Email</label>
+    <label class="col-form-label col-sm-2 required" for="user_email">Email</label>
     <div class="col-sm-10">
-      <input aria-required="true" class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
+      <input class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
     </div>
   </div>
-  <div class="mb-3">
-    <label class="form-label" for="user_feet">Feet</label>
-    <input class="form-control" id="user_feet" name="user[feet]" type="text" value="5">
+  <div class="row">
+    <div class="col">
+      <div class="mb-3">
+        <label class="form-label" for="user_feet">Feet</label>
+        <input class="form-control" id="user_feet" name="user[feet]" type="text" value="5">
+      </div>
+    </div>
+    <div class="col">
+      <div class="mb-3">
+        <label class="form-label" for="user_inches">Inches</label>
+        <input class="form-control" id="user_inches" name="user[inches]" type="text" value="7">
+      </div>
+    </div>
   </div>
   <div class="mb-3">
-    <label class="form-label" for="user_inches">Inches</label>
-    <input class="form-control" id="user_inches" name="user[inches]" type="text" value="7">
-  </div>
-  <div class="mb-3 row">
-    <div class="col-sm-10 offset-sm-2">
-      <input class="btn btn-secondary" data-disable-with="Create User" name="commit" type="submit" value="Create User">
+    <div class="form-check">
+      <input autocomplete="off" name="user[terms]" type="hidden" value="0">
+      <input class="form-check-input" id="user_terms" name="user[terms]" type="checkbox" value="1">
+      <label class="form-check-label" for="user_terms">Terms</label>
     </div>
   </div>
+  <input class="btn btn-secondary" data-disable-with="Create User" name="commit" type="submit" value="Create User">
 </form>
 ```
 
 A form-level `layout: :inline` can't be overridden because of the way Bootstrap 4 implements in-line layouts. One possible work-around is to leave the form-level layout as default, and specify the individual fields as `layout: :inline`, except for the fields(s) that should be other than in-line.
 
-### Custom Form Element Styles
-
-The `custom` option can be used to replace the browser default styles for check boxes and radio buttons with dedicated Bootstrap styled form elements. Here's an example:
-
-![Example 42](demo/doc/screenshots/bootstrap/readme/42_example.png "Example 42")
-```erb
-<%= bootstrap_form_for(@user) do |f| %>
-  <%= f.email_field :email %>
-  <%= f.password_field :password %>
-  <%= f.check_box :remember_me, custom: true %>
-  <%= f.submit "Log In" %>
-<% end %>
-```
-
-This generates:
-
-```html
-<form accept-charset="UTF-8" action="/users" class="new_user" id="new_user" method="post">
-  <div class="mb-3">
-    <label class="form-label required" for="user_email">Email</label>
-    <input aria-required="true" class="form-control" id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
-  </div>
-  <div class="mb-3">
-    <label class="form-label" for="user_password">Password</label>
-    <input class="form-control" id="user_password" name="user[password]" type="password">
-  </div>
-  <div class="form-check mb-3">
-    <input autocomplete="off" name="user[remember_me]" type="hidden" value="0">
-    <input class="form-check-input" custom="true" id="user_remember_me" name="user[remember_me]" type="checkbox" value="1">
-    <label class="form-check-label" for="user_remember_me">Remember me</label>
-  </div>
-  <input class="btn btn-secondary" data-disable-with="Log In" name="commit" type="submit" value="Log In">
-</form>
-```
-
 ### Floating Labels
 
 The `floating` option can be used to enable Bootstrap 5's floating labels. This option is supported on text fields
 and dropdowns. Here's an example:
 
-![Example 43](demo/doc/screenshots/bootstrap/readme/43_example.png "Example 43")
+![Example 44](demo/doc/screenshots/bootstrap/readme/44_example.png "Example 44")
 ```erb
 <%= bootstrap_form_for(@user) do |f| %>
   <%= f.email_field :email, floating: true %>
@@ -1332,7 +1387,7 @@ This generates:
 ```html
 <form accept-charset="UTF-8" action="/users" class="new_user" id="new_user" method="post">
   <div class="mb-3 form-floating">
-    <input aria-required="true" class="form-control" id="user_email" name="user[email]" placeholder="Email" required="required" type="email" value="steve@example.com">
+    <input class="form-control" id="user_email" name="user[email]" placeholder="Email" required="required" type="email" value="steve@example.com">
     <label class="form-label required" for="user_email">Email</label>
   </div>
   <div class="mb-3 form-floating">
@@ -1364,10 +1419,15 @@ Rails normally wraps fields with validation errors in a `div.field_with_errors`,
 By default, fields that have validation errors will be outlined in red and the
 error will be displayed below the field. Here's an example:
 
-![Example 44](demo/doc/screenshots/bootstrap/readme/44_example.png "Example 44")
+![Example 45](demo/doc/screenshots/bootstrap/readme/45_example.png "Example 45")
 ```erb
 <%= bootstrap_form_for(@user_with_error) do |f| %>
   <%= f.email_field :email %>
+  <%= f.collection_radio_buttons :misc, Skill.all, :id, :name %>
+  <%= f.collection_check_boxes :preferences, [[1, 'Good'], [2, 'Bad']], :first, :second %>
+  <%= f.fields_for :address do |af| %>
+    <%= af.text_field :street %>
+  <% end %>
 <% end %>
 ```
 
@@ -1377,7 +1437,37 @@ Generated HTML:
 <form accept-charset="UTF-8" action="/users" class="new_user" id="new_user" method="post">
   <div class="mb-3">
     <label class="form-label required" for="user_email">Email</label>
-    <input aria-required="true" class="form-control is-invalid" id="user_email" name="user[email]" required="required" type="email" value="steve.example.com">
+    <input class="form-control is-invalid" id="user_email" name="user[email]" required="required" type="email" value="steve.example.com">
+    <div class="invalid-feedback">is invalid</div>
+  </div>
+  <div class="mb-3">
+    <label class="form-label" for="user_misc">Misc</label>
+    <div class="form-check">
+      <input checked class="form-check-input is-invalid" id="user_misc_1" name="user[misc]" type="radio" value="1">
+      <label class="form-check-label" for="user_misc_1">Mind reading</label>
+    </div>
+    <div class="form-check">
+      <input class="form-check-input is-invalid" id="user_misc_2" name="user[misc]" type="radio" value="2">
+      <label class="form-check-label" for="user_misc_2">Farming</label>
+      <div class="invalid-feedback">is invalid</div>
+    </div>
+  </div>
+  <input autocomplete="off" id="user_preferences" name="user[preferences][]" type="hidden" value="">
+  <div class="mb-3">
+    <label class="form-label" for="user_preferences">Preferences</label>
+    <div class="form-check">
+      <input checked class="form-check-input is-invalid" id="user_preferences_1" name="user[preferences][]" type="checkbox" value="1">
+      <label class="form-check-label" for="user_preferences_1">Good</label>
+    </div>
+    <div class="form-check">
+      <input class="form-check-input is-invalid" id="user_preferences_2" name="user[preferences][]" type="checkbox" value="2">
+      <label class="form-check-label" for="user_preferences_2">Bad</label>
+      <div class="invalid-feedback">is invalid</div>
+    </div>
+  </div>
+  <div class="mb-3">
+    <label class="form-label" for="user_address_attributes_street">Street</label>
+    <input class="form-control is-invalid" id="user_address_attributes_street" name="user[address_attributes][street]" type="text" value="Bar">
     <div class="invalid-feedback">is invalid</div>
   </div>
 </form>
@@ -1396,7 +1486,7 @@ You can turn off inline errors for the entire form like this:
 You can also display validation errors in the field's label; just turn
 on the `:label_errors` option. Here's an example:
 
-![Example 45](demo/doc/screenshots/bootstrap/readme/45_example.png "Example 45")
+![Example 46](demo/doc/screenshots/bootstrap/readme/46_example.png "Example 46")
 ```erb
 <%= bootstrap_form_for(@user_with_error, label_errors: true) do |f| %>
   <%= f.email_field :email %>
@@ -1409,7 +1499,7 @@ Generated HTML:
 <form accept-charset="UTF-8" action="/users" class="new_user" id="new_user" method="post">
   <div class="mb-3">
     <label class="form-label required text-danger" for="user_email">Email is invalid</label>
-    <input aria-required="true" class="form-control is-invalid" id="user_email" name="user[email]" required="required" type="email" value="steve.example.com">
+    <input class="form-control is-invalid" id="user_email" name="user[email]" required="required" type="email" value="steve.example.com">
   </div>
 </form>
 ```
@@ -1429,7 +1519,7 @@ To display an error message with an error summary, you can use the
 `alert_message` helper. This won't output anything unless a model validation
 has failed.
 
-![Example 46](demo/doc/screenshots/bootstrap/readme/46_example.png "Example 46")
+![Example 47](demo/doc/screenshots/bootstrap/readme/47_example.png "Example 47")
 ```erb
 <%= bootstrap_form_for @user_with_error do |f| %>
   <%= f.alert_message "Please fix the errors below." %>
@@ -1445,6 +1535,7 @@ Which outputs:
     <ul class="rails-bootstrap-forms-error-summary">
       <li>Email is invalid</li>
       <li>Misc is invalid</li>
+      <li>Preferences is invalid</li>
     </ul>
   </div>
 </form>
@@ -1452,7 +1543,7 @@ Which outputs:
 
 You can turn off the error summary like this:
 
-![Example 47](demo/doc/screenshots/bootstrap/readme/47_example.png "Example 47")
+![Example 48](demo/doc/screenshots/bootstrap/readme/48_example.png "Example 48")
 ```erb
 <%= bootstrap_form_for @user_with_error do |f| %>
   <%= f.alert_message "Please fix the errors below.", error_summary: false %>
@@ -1469,7 +1560,7 @@ This generates:
 
 To output a simple unordered list of errors, use the `error_summary` helper.
 
-![Example 48](demo/doc/screenshots/bootstrap/readme/48_example.png "Example 48")
+![Example 49](demo/doc/screenshots/bootstrap/readme/49_example.png "Example 49")
 ```erb
 <%= bootstrap_form_for @user_with_error do |f| %>
   <%= f.error_summary %>
@@ -1483,6 +1574,7 @@ Which outputs:
   <ul class="rails-bootstrap-forms-error-summary">
     <li>Email is invalid</li>
     <li>Misc is invalid</li>
+    <li>Preferences is invalid</li>
   </ul>
 </form>
 ```
@@ -1491,7 +1583,7 @@ Which outputs:
 
 If you want to display a custom inline error for a specific attribute not represented by a form field, use the `errors_on` helper.
 
-![Example 49](demo/doc/screenshots/bootstrap/readme/49_example.png "Example 49")
+![Example 50](demo/doc/screenshots/bootstrap/readme/50_example.png "Example 50")
 ```erb
 <%= bootstrap_form_for @user_with_error do |f| %>
   <%= f.errors_on :email %>
@@ -1508,7 +1600,7 @@ Which outputs:
 
 You can hide the attribute name like this:
 
-![Example 50](demo/doc/screenshots/bootstrap/readme/50_example.png "Example 50")
+![Example 51](demo/doc/screenshots/bootstrap/readme/51_example.png "Example 51")
 ```erb
 <%= bootstrap_form_for @user_with_error do |f| %>
   <%= f.errors_on :email, hide_attribute_name: true %>
@@ -1525,7 +1617,7 @@ Which outputs:
 
 You can also use a custom class for the wrapping div, like this:
 
-![Example 51](demo/doc/screenshots/bootstrap/readme/51_example.png "Example 51")
+![Example 52](demo/doc/screenshots/bootstrap/readme/52_example.png "Example 52")
 ```erb
 <%= bootstrap_form_for @user_with_error do |f| %>
   <%= f.errors_on :email, custom_class: 'custom-error' %>
@@ -1560,7 +1652,7 @@ ActiveModel::Validations::PresenceValidator.
 
 In cases where this behaviour is undesirable, use the `required` option to force the class to be present or absent:
 
-![Example 52](demo/doc/screenshots/bootstrap/readme/52_example.png "Example 52")
+![Example 53](demo/doc/screenshots/bootstrap/readme/53_example.png "Example 53")
 ```erb
 <%= f.password_field :login, label: "New Username", required: true %>
 <%= f.password_field :password, label: "New Password", required: false %>
@@ -1571,7 +1663,7 @@ This generates:
 ```html
 <div class="mb-3">
   <label class="form-label required" for="user_login">New Username</label>
-  <input aria-required="true" class="form-control" id="user_login" name="user[login]" required="required" type="password">
+  <input class="form-control" id="user_login" name="user[login]" required="required" type="password">
 </div>
 <div class="mb-3">
   <label class="form-label" for="user_password">New Password</label>
@@ -1583,7 +1675,7 @@ This generates:
 
 Adding a form control for a `belongs_to` field will automatically pick up the associated presence validator.
 
-![Example 53](demo/doc/screenshots/bootstrap/readme/53_example.png "Example 53")
+![Example 54](demo/doc/screenshots/bootstrap/readme/54_example.png "Example 54")
 ```erb
 <%= bootstrap_form_for(@address, url: '/address') do |f| %>
   <%= f.collection_select :user_id, @users, :id, :email, include_blank: "Select a value" %>
@@ -1626,6 +1718,98 @@ Generated HTML:
 </form>
 ```
 
+## Disabled fields
+
+Fields can be disabled using the standard Rails form helper option.
+
+![Example 55](demo/doc/screenshots/bootstrap/readme/55_example.png "Example 55")
+```erb
+<%= bootstrap_form_for @user do |f| %>
+  <div class="row g-3">
+    <div class="col-auto"><%= f.email_field :email, disabled: true %></div>
+    <div class="col-auto"><%= f.password_field :password, disabled: true %></div>
+    <div class="col-auto"><%= f.text_area :comments, disabled: true %></div>
+    <div class="col-auto"><%= f.text_field :status, disabled: true %></div>
+    <div class="col-auto"><%= f.number_field :misc, label: "Number", disabled: true %></div>
+    <div class="col-auto"><%= f.radio_button :preferences, 1, disabled: true %></div>
+    <div class="col-auto"><%= f.check_box :terms, disabled: true %></div>
+    <div class="col-auto"><%= f.select :type, [1,2,3], {}, disabled: true %></div>
+    <div class="col-auto"><%= f.datetime_field :created_at, disabled: true %></div>
+  </div>
+  <%= f.primary disabled: true %>
+<% end %>
+```
+
+Generated HTML:
+
+```html
+<form accept-charset="UTF-8" action="/users" class="new_user" id="new_user" method="post">
+  <div class="row g-3">
+    <div class="col-auto">
+      <div class="mb-3">
+        <label class="form-label required" for="user_email">Email</label>
+        <input class="form-control" disabled id="user_email" name="user[email]" required="required" type="email" value="steve@example.com">
+      </div>
+    </div>
+    <div class="col-auto">
+      <div class="mb-3">
+        <label class="form-label" for="user_password">Password</label>
+        <input class="form-control" disabled id="user_password" name="user[password]" type="password">
+      </div>
+    </div>
+    <div class="col-auto">
+      <div class="mb-3">
+        <label class="form-label" for="user_comments">Comments</label>
+        <textarea class="form-control" disabled id="user_comments" name="user[comments]">
+</textarea>
+      </div>
+    </div>
+    <div class="col-auto">
+      <div class="mb-3">
+        <label class="form-label" for="user_status">Status</label>
+        <input class="form-control" disabled id="user_status" name="user[status]" type="text">
+      </div>
+    </div>
+    <div class="col-auto">
+      <div class="mb-3">
+        <label class="form-label" for="user_misc">Number</label>
+        <input class="form-control" disabled id="user_misc" name="user[misc]" type="number">
+      </div>
+    </div>
+    <div class="col-auto">
+      <div class="form-check disabled">
+        <input class="form-check-input" disabled id="user_preferences_1" name="user[preferences]" type="radio" value="1">
+        <label class="form-check-label" for="user_preferences_1">1</label>
+      </div>
+    </div>
+    <div class="col-auto">
+      <div class="form-check mb-3">
+        <input autocomplete="off" disabled name="user[terms]" type="hidden" value="0">
+        <input class="form-check-input" disabled id="user_terms" name="user[terms]" type="checkbox" value="1">
+        <label class="form-check-label" for="user_terms">Terms</label>
+      </div>
+    </div>
+    <div class="col-auto">
+      <div class="mb-3">
+        <label class="form-label" for="user_type">Type</label>
+        <select class="form-select" disabled id="user_type" name="user[type]">
+          <option value="1">1</option>
+          <option value="2">2</option>
+          <option value="3">3</option>
+        </select>
+      </div>
+    </div>
+    <div class="col-auto">
+      <div class="mb-3">
+        <label class="form-label" for="user_created_at">Created at</label>
+        <input class="form-control" disabled id="user_created_at" name="user[created_at]" type="datetime-local">
+      </div>
+    </div>
+  </div>
+  <input class="btn btn-primary" data-disable-with="Create User" disabled name="commit" type="submit" value="Create User">
+</form>
+```
+
 ## Internationalization
 
 bootstrap_form follows standard rails conventions so it's i18n-ready. See more