GOV.UK Design System Form Builder for Rails

This gem provides a easy-to-use form builder that generates forms that are fully-compliant with version 3.6.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.

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
end

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,
    @departments,
    :id,
    :name,
    :description,
    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:

bundle

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.

To help keep the logs clean and tidy, please configure git to use your full name:

git config --global user.name "Julius Hibbert"

Thanks 👩🏽‍⚖️

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

duncanjbrown / govuk_design_system_formbuilder