Gov.UK Design System in C#/ASP.Net Core

This is a collection of Gov.UK Design System components build in C# / ASP.Net Core.

It's the C# equivalent of the Gov.UK Prototyping Kit Nunjucks templates.

To use this library your project will need to include some content from the GOV.UK Frontend NPM package used by the components. For an example of how to include the content from the NPM package see package.json from the DESNZ HER project. This library currently works with GOV.UK Frontend v4.8.0 (and requires at least v4.8.0.)

Warning: work in progress

Warning: This is very much a work in progress!
Only a subset of the components have been built and there is the possibility of breaking changes as we make bug fixes / add extra features.

Please feel free to use this in your own project. You can see our contributing guide here.

If you do, please let us know, so we can avoid making changes that will cause problems for you.
Email: Dan Corder [email protected]

Breaking change - 13/03/2024

As of 13/03/2024 the path to the Queen's crown asset in Header.cshtml has been changed to that of the new King's Crown, per the GovUkFrontend v4.8.0 release notes. This will break the fallback image for IE8 if that asset doesn't exist at the path specified.
This change is as follows:

• Previous path: /assets/images/govuk-logotype-crown.png
• New path: /assets/images/govuk-logotype-tudor-crown.png

It is possible to use this with a version lower than v4.8.0 of the GovUkFrontend library, but this asset in particular must be imported manually to the path specified to avoid breaking.

Breaking change - 13/05/22

As of the 13/05/22 the validation used by this library has changed so that it is more in line with the standard ASP.Net validation. The main impacts are:

• View models do not need to inherit from GovUkViewModel
• In controllers, instead of viewModel.HasAnyErrors you can use the more standard ModelState.IsValid
• You should be able to use any of the built in ASP.Net validation attributes and have their error messages appear in the GovUkErrorSummary

If you need to use/fix the old version of the library it is now on the pre-2022-05-13 branch

How to use

This library can be used in two ways:

• View components only
• View components + validation / error message generation

These features are interoperable and you can use as much or as little of them as you like in your project - it's not necessary to migrate totally to using this library.

View components

e.g. for a Gov.UK Button

On the Design System website:
https://design-system.service.gov.uk/components/button
the Nunjucks code would look like this:

{% from "govuk/components/button/macro.njk" import govukButton %}

{{ govukButton({
    text: "Save and continue"
}) }}

The C# code would look like this:

@using GovUkDesignSystem
@using GovUkDesignSystem.GovUkDesignSystemComponents

@(Html.GovUkButton(new ButtonViewModel
{
    Text = "Save and continue"
}))

e.g. for a Text Input
https://design-system.service.gov.uk/components/text-input/
the C# code would be:

@(Html.GovUkTextInput(new TextInputViewModel
{
    Label = new LabelViewModel
    {
        Text = "Your email address"
    },
    Name = "EmailAddress",
    InputMode = "email"
}))

View components + validation / error message generation

This library includes a number of validation attributes that can be used alongside the built in MVC validation attributes. The GovUkErrorSummary will display any errors in the model state.

For property types where a badly formed value may make it impossible to bind the submitted value to the model, this library provides custom model binders that will generate binding failure messages that match the GovUK design system suggested error messages.

Here's an example of how to get automatic error message generation for a mandatory integer field.

In your application's Startup class add the following to the ConfigureServices method:

    services.AddControllersWithViews(options =>
        options.ModelMetadataDetailsProviders.Add(new GovUkDataBindingErrorTextProvider()));

On your view-model:

• Use a nullable integer (int?) property
• Add the ModelBinder attribute with typeof(GovUkMandatoryIntBinder)
• Add the GovUkDataBindingIntErrorText attribute to specify the text to use within the error messages.

public class MyViewModel : GovUkViewModel
{
    [ModelBinder(typeof(GovUkMandatoryIntBinder))]
    [GovUkDataBindingIntErrorText(
        ErrorMessageIfMissing = "Enter the number of children you have",
        NameAtStartOfSentence = "Number of children"
    )]
    public int? NumberOfChildren
}

On the view:

@using GovUkDesignSystem
@using GovUkDesignSystem.GovUkDesignSystemComponents

@model MyViewModel

@(Html.GovUkErrorSummary(ViewData.ModelState))

@(Html.GovUkTextInputFor(
    m => m.NumberOfChildren,
    labelOptions: new LabelViewModel
    {
        Text = "How many children do you have?"
    }
))

On the controller:

• Check ModelState.IsValid as normal

[HttpPost("url-to-action")]
public IActionResult ActionName(MyViewModel viewModel)
{
    // Return the user back to the page if there's an error
    if (!ModelState.IsValid)
    {
        return View("ViewName", viewModel);
    }
}

Packaging

Currently this project is not published on Nuget.

To manually create a Nuget package from the code:

• Ensure you have the dotnet cli tool installed (if dotnet --version works then you should be fine, otherwise in stall the .NET Core SDK from https://www.microsoft.com/net/download/)
• Change directory to GovUkDesignSystem
• Run dotnet pack -p:PackageVersion=<your version here> -c Release -o .

Development

Pre-requisites

• .Net 3.1 (https://dotnet.microsoft.com/en-us/download/dotnet/3.1)
• Winmerge (https://winmerge.org/)

Project structure

The project contains 3 general folders:

• GovUkDesignSystem: Where all features such as components and attributes are located
• GovUkDesignSystem.UnitTests: Where tests regarding functionality should be added
• GovUkDesignSystem.SnapshotTests: Where tests regarding how HTML components are rendered should be added

Snapshot tests

We use Approval tests (https://approvaltests.com/) to ensure HTML components are rendered properly.

After writing a test and running it, a Winmerge window will open with the test result on the left, and the expected value on the right. Edit the file to the right to represent what the test outcome should be (in the case of newly added components, for example, copying the contents of the left file) and save the changes.