bootstrap_form renders Bootstrap 5 markup from Rails form helpers

A form builder that wraps the Rails helpers instead of replacing them

bootstrap_form is a Rails form builder that makes it easy to integrate Bootstrap v5-style forms into a Rails application. The important word in that sentence is augment. The README says the gem provides form helpers that augment the Rails form helpers, and that the generated helpers produce the form field, its label, and all the Bootstrap mark-up required for proper Bootstrap display.

The way you use it is deliberately close to what you already know. You start a form with bootstrap_form_with, bootstrap_form_for, or bootstrap_form_tag in a view file, and you get a form builder that calls the bootstrap_form helpers instead of the standard Rails helpers. From there you render one or more fields. The README assumes you already understand how the standard Rails form helpers work, which tells you the learning curve is close to zero for a Rails developer.

What you get in exchange is less view code. The README lists the benefits plainly: it reduces the amount of code in your .erb files, it gets you going faster with Bootstrap because you do not need to learn all the rules of Bootstrap form mark-up, it reduces errors because you are typing less, and it makes the logic of the form easier to see because it is not mixed in with the Bootstrap mark-up.

There is also an escape hatch, which is the detail that makes the gem usable in a real codebase. The README lists a way to escape to the Rails form helpers if you need to do something that bootstrap_form cannot do, so a form that needs unusual markup is not a reason to abandon the builder for that view.

The generated HTML carries mb-3 wrappers, form-label and required classes

The clearest way to see what the gem does is the example the README gives. The view code is four lines:

<%= bootstrap_form_for(@user) do |f| %>
  <%= f.email_field :email %>
  <%= f.password_field :password %>
  <%= f.check_box :remember_me %>
  <%= f.submit "Log In" %>
<% end %>

And the HTML it produces is fully expanded in the README, with each field wrapped in a div with the mb-3 margin class, labels carrying form-label, inputs carrying form-control, and the checkbox rendered as a form-check with a hidden 0 field before the real input. The required field also gets a required class on the label and a required="required" attribute on the input, which is the Rails and Bootstrap convention for styling required fields.

That expansion is the value proposition in one artefact. None of that wrapper div, that label class, or that combination of check box markup is something you would want to type in every view, and Bootstrap's grid and spacing rules are exactly the kind of detail that gets forgotten until someone reviews the form in a browser.

The README also notes that all the examples in it are generated with the configuration option group_around_collections set to true, which is worth knowing before you compare your own output against the documentation and conclude something is broken.

Installing the gem means adding Bootstrap, the gem, and sometimes its CSS

The gem needs Bootstrap present, and the README is clear that the gem itself does not care how Bootstrap gets into your application. For a new Rails app, the suggested command is:

rails new --javascript=esbuild --css=bootstrap <application-name>

with the note that esbuild can be any of the options except the default importmaps. For an existing project that already runs a front-end preprocessor, the README suggests installing Bootstrap through it, for example:

yarn add bootstrap popper.js

Then the gem goes into the Gemfile:

gem "bootstrap_form", "~> 5.6"

followed by bundle install.

The CSS step is conditional, and the README explains the condition. bootstrap_form uses a very small number of its own CSS styles, and those styles are used in the HTML generated by the error_summary and alert_message error helpers and by the date_select, time_select and datetime_select helpers. If you are not using those helpers, you do not need the styles.

If you do need them, the import syntax depends on your asset pipeline. With Propshaft, which the README notes is the Rails 8 default, the styles go into your CSS bundle like this:

@use "rails_bootstrap_forms";

With Sprockets, the pre-Rails-8 path, the import is different:

@import "rails_bootstrap_forms.css";

The README suggests checking your Gemfile to see whether you are using sprockets-rails or propshaft, because getting this wrong produces an error rather than a subtle styling problem. It also mentions the bootstrap gem as an alternative way to install Bootstrap itself, while noting that the maintainers have not used that approach for a few years and asking for an issue report if it does not work.

Error messages sit below the field by default, and the HTML5 conflict is documented

The validation handling is the feature with the most nuance. The README says the gem places validation error messages below the field they correspond to, by default. You can also put the error messages after the label, or turn off the bootstrap_form validation error handling and do it yourself.

There is a caveat attached to that behaviour, and it is the most useful sentence in the README for anyone evaluating the gem: this applies to Rails-generated validation messages, and HTML 5 client-side validation and Rails validation out of the box do not really work well together. The README links a discussion of the challenges and some solutions.

That is a genuine design constraint rather than a defect in the gem. Browser validation pops up its own message on submit and blocks the request, so a server-side error message never appears for that field, and the user sees an inconsistent experience depending on which field failed first. Any team shipping Bootstrap 5 forms with Rails model validation has to decide who owns validation, and the gem's default is to render the server errors and leave the HTML5 attributes, including the automatic required attribute, in place.

The required attribute is the other half of this. The gem adds mark-up for the required attribute on required fields automatically, so a field that the model validates as required carries the browser hint as well. The README lists automatic required mark-up as one of the core features of the gem, alongside help text and horizontal form mark-up.

Help text, horizontal forms, and a long list of options to tweak the markup

Beyond validation, the README lists a set of features that cover the parts of Bootstrap form styling that come up repeatedly. There is an easy way to consistently show help text on fields, and there is mark-up for Bootstrap horizontal forms, which the README describes as labels to the left of their fields, like a traditional desktop application, and which it presents as an option rather than a default.

Then there are many options to modify or augment the generated mark-up, and the README links them under a form helpers section. The scope of that option set matters more than any individual flag, because it is the difference between a form builder you fight and one you configure. Every Bootstrap form variant has small details, and if the gem exposes a setting for each of them, the view code stays declarative.

The horizontal form option is worth singling out, because it is the one that changes the shape of the page rather than the shape of a widget. A desktop-style layout with left-aligned labels is not a CSS class you can bolt on afterwards without restructuring the markup, so having the builder emit it directly is a real convenience for internal tools and admin panels.

The README also mentions bootstrap_form_tag for forms that are not backed by a model, and states that its usage is the same as bootstrap_form_for except that no model is involved.

The demo app runs under Docker Compose with a Selenium container

The repository carries a working example application, and the Docker setup is the clearest picture of how the project is developed. The compose.yml file defines two services. The web service runs a Rails application image, with the source directory mounted into the container, and a named volume for the home directory. The selenium service runs a standalone Chrome image with 2gb of shared memory, and the web service receives its host and port through the SELENIUM_HOST and SELENIUM_PORT environment variables.

The port mapping explains the rest of the configuration. The web service exposes 3000, 3001 and 5990, and the selenium service exposes 7900, which the selenium image exposes for browser viewing. The variables TEST_APP_HOST and TEST_APP_PORT tell the test suite where the application under test is reachable, which is why the demo works with a browser driver in a separate container.

The repository also has a DOCKER.md file, a.devcontainer.json for VS Code based development, a Dangerfile for pull request checks, a.rubocop.yml, and a Rakefile. The demo directory has its own package.json, yarn.lock, webpack.config.js, a.postcssrc.yml and a Procfile.dev, so the demo application is a separate front-end project rather than a folder of fixtures.

For a contributor, this means the environment is reproducible without installing Chrome locally, which matters for a form builder whose output is HTML that has to be checked in a real browser.

MIT licensed, with documented major version upgrades

The licence is MIT, and the LICENSE.txt file in the repository is the authoritative text. That is a permissive licence with no copyleft obligations for the Rails application that uses the gem, and this is a licensing statement rather than legal advice.

The version history shows a project that has crossed several major versions and documented each crossing. The repository root holds UPGRADE-4.0.md and UPGRADE-5.0.md alongside CHANGELOG.md and RELEASING.md, and an OLD-README.md that preserves the previous documentation. Recent releases are v5.6.1 on 2026-05-04, v5.6.0 on 2026-01-26 and v5.5.0 on 2025-10-30. The repository is not archived and the last push was on 2026-10-18.

Those upgrade guides are the practical part for an adopter. A form builder's output is markup, so a major version change can shift the HTML your tests assert on, your custom CSS may target, or your accessibility expectations rely on, even when no Ruby API changed. The README's requirements are the current floor: Ruby 3.2+, Rails 7.2+, and Bootstrap 5.0+, and the gem supports at minimum the currently supported versions of Ruby and Rails.

Because Bootstrap 5 dropped the jQuery plugin conventions of Bootstrap 4, the major version line of this gem is tied to the major version of the CSS framework, and an application that has not finished migrating its front-end to Bootstrap 5 is not a candidate for the current gem.

Editorial conclusion

Adopt bootstrap_form if your Rails application already ships Bootstrap 5 and you want form markup, labels, error placement and required attributes generated consistently instead of hand written in each view. Do not adopt it if your project is on a pre-5.0 Bootstrap or an older Rails, since the gem targets Bootstrap 5.0+, Ruby 3.2+ and Rails 7.2+, and it has no value for an application that has standardised on Tailwind. Before you install, decide whether you need the gem's own CSS, because the rails_bootstrap_forms styles are only required for the error_summary, alert_message and date and time select helpers, and check whether your asset pipeline is Propshaft or Sprockets before you add the import.

Frequently asked questions

Official sources

1. bootstrap-ruby/bootstrap_form on GitHub
2. Issues
3. License: MIT
4. README
5. Releases