Skip to content
GOV.UK-compliant form builder for Rails
Ruby HTML CSS Makefile
Branch: master
Clone or download

GOV.UK Design System Form Builder for Rails

Build Status Maintainability Gem Version Gem Test Coverage Dependabot Status GitHub license GOV.UK Design System Version

This gem provides a easy-to-use form builder that generates forms that are fully-compliant with version 3.4.0 of the GOV.UK Design System, minimising the amount of markup you need to write.

In addition to the basic markup, the more-advanced functionality of the Design System is exposed via the API. Adding JavaScript-enhanced word count checking to text areas or setting the size and weight of labels on text fields requires only a single argument.

Documentation 📚

The gem comes with a full guide that covers most aspects of day-to-day use, along with code and output examples. The guide is generated from the builder itself so it will always be up to date.

If you're still not sure what a form builder is or how it works, don't worry! This screencast should give you an idea of what's on offer and the official guide goes into a bit more depth on how everything works.

Netlify Status

What's included 🧳

  • 100% compatibility with the GOV.UK Design System
  • Full control of labels, hints, fieldsets and legends
  • No overwriting of Rails' default form helpers
  • Automatic ARIA associations between hints, errors and inputs
  • Most helpers take blocks for arbitrary content
  • Additional params for programmatically adding hints to check box and radio button collections
  • No external dependencies
  • An exhaustive test suite
  • Extensive technical documentation

Installation 🏗

You can install the form builder gem by running the gem install govuk_design_system_formbuilder or by adding the following line to your Gemfile:

gem 'govuk_design_system_formbuilder'

To make full use of this tool, you will need a Rails application with the latest GOV.UK Frontend assets installed and configured.

To get up and running quickly and easily try kickstarting your project with a pre-configured template:

Setup 🔧

To use the form builder in an ad hoc basis you can specify it as an argument to form_for or form_with:

= form_for @some_object, builder: GOVUKDesignSystemFormBuilder::FormBuilder do |f|

To set it globally, just add this line to your ApplicationController:

class ApplicationController < ActionController::Base
  default_form_builder GOVUKDesignSystemFormBuilder::FormBuilder

Now we can get started!

= form_for @person do |f|

  = f.govuk_text_field :full_name, label: { text: "Your full name" }

  = f.govuk_number_field :age, label: { text: "Age" }

  = f.govuk_collection_select :department_id,
    label: { text: "Which department do you work for?" },
    hint_text: "If you don't know ask your manager" }

  = f.govuk_submit 'Away we go!'

Developing and running the tests 👨🏻‍🏭

The form builder is covered by RSpec, to run all the tests first ensure that all of the development and testing prerequisite gems are installed. At the root of a freshly-cloned repo run:


Now, if everything was successful, run RSpec:

bundle exec rspec -fd

Contributing 📦

Bug reports and feature requests are most welcome, please raise an issue or submit a pull request.

Currently we're using GOVUK Lint to ensure code meets the GOV.UK guidelines. Please ensure that any PRs also adhere to this standard.

Thanks 👩🏽‍⚖️

This project was inspired by Ministry of Justice's GovukElementsFormBuilder, but is leaner, more modular and written in a more idiomatic style.

You can’t perform that action at this time.