# GOV.UK Design System Form Builder for Rails
[](https://github.com/DFE-Digital/govuk-formbuilder/actions)
[](https://codeclimate.com/github/DFE-Digital/govuk-formbuilder/maintainability)
[](https://badge.fury.io/rb/govuk_design_system_formbuilder)
[](https://rubygems.org/gems/govuk_design_system_formbuilder)
[](https://codeclimate.com/github/DFE-Digital/govuk-formbuilder/test_coverage)
[](https://github.com/DFE-Digital/govuk-formbuilder/blob/main/LICENSE)
[](https://design-system.service.gov.uk)
[](https://weblog.rubyonrails.org/releases/)
[](https://www.ruby-lang.org/en/downloads/)
This library provides an easy-to-use form builder for the [GOV.UK Design System](https://design-system.service.gov.uk/).
It is intended to make creating forms **quick**, **easy** and **familiar** for Ruby on Rails developers.
## Documentation 📚
The gem comes with [a full guide](https://govuk-form-builder.netlify.app/) that
covers most aspects of day-to-day use, along with code and output examples. The
examples in the guide are generated from the builder itself so it will always
be up to date.
[](https://app.netlify.com/sites/govuk-form-builder/deploys)
## What's included 🧳
* 100% compatibility with the GOV.UK Design System
* Full control of labels, legends, hints, captions and fieldsets
* 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
* Full I18n support
* Automatic handling of ActiveRecord validation error messages
* No external dependencies
* An exhaustive test suite
* [Extensive technical documentation](https://www.rubydoc.info/gems/govuk_design_system_formbuilder/GOVUKDesignSystemFormBuilder/Builder)
## 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`:
```sh
gem 'govuk_design_system_formbuilder'
```
To make full use of this tool, you will need a Rails application with the latest [GOV.UK
Frontend](https://github.com/alphagov/govuk-frontend) assets installed and
configured.
To get up and running quickly and easily try kickstarting your project with a
pre-configured template:
* [DfE Boilerplate](https://github.com/DFE-Digital/govuk-rails-boilerplate)
* [DEFRA Ruby Template](https://github.com/DEFRA/defra-ruby-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`. These examples are written in [Slim](https://slim-lang.com) but
other templating languages like ERB and [Haml](https://haml.info/) work just as well.
```slim
= form_for @some_object, builder: GOVUKDesignSystemFormBuilder::FormBuilder do |f|
...
```
To set it globally, just add this line to your `ApplicationController`:
```ruby
class ApplicationController < ActionController::Base
default_form_builder GOVUKDesignSystemFormBuilder::FormBuilder
end
```
Now we can get started!
```slim
= 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 tested with RSpec. To run all the tests first ensure that
the development and testing prerequisite gems are installed. At the root of a
freshly-cloned repo run:
```sh
bundle
```
Now, if everything was successful, run RSpec:
```sh
bundle exec rspec
```
## Contributing 📦
Bug reports and feature requests are most welcome, please raise an issue or
submit a pull request.
Currently we're using [GOVUK Lint](https://github.com/alphagov/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:
```sh
git config --global user.name "Julius Hibbert"
```
## Services using this library
Approximately [40 services use this library](https://github.com/DFE-Digital/govuk-formbuilder/network/dependents),
here are a few from the DfE, MoJ, and
BEIS.
* [Apply for teacher training](https://www.github.com/DFE-Digital/apply-for-teacher-training)
* [Teaching Vacancies](https://www.github.com/DFE-Digital/teaching-vacancies)
* [Get a teacher training adviser](https://www.github.com/DFE-Digital/get-teacher-training-adviser-service/)
* [Claim for crown court defence](https://www.github.com/ministryofjustice/Claim-for-Crown-Court-Defence)
* [Appeal to the tax tribunal](https://www.github.com/ministryofjustice/tax-tribunals-datacapture)
* [Apply to court about child arrangements](https://www.github.com/ministryofjustice/c100-application)
* [Trade Tariff duty calculator](https://www.github.com/trade-tariff/trade-tariff-duty-calculator)
* [Report your official development assistance](https://www.github.com/UKGovernmentBEIS/beis-report-official-development-assistance)
## Thanks 👩🏽⚖️
This project was inspired by [Ministry of Justice's GovukElementsFormBuilder](https://github.com/ministryofjustice/govuk_elements_form_builder),
but is leaner, more modular and written in a more idiomatic style.