GitHub - x-govuk/govuk-frontend-aspnetcore: ASP.NET Core integration for GOV.UK Design system

This library simplifies setting up an ASP.NET Core application to use the GOV.UK Design System. It includes tag helpers to produce GDS components which integrate with ASP.NET Core's model binding system.

Installation

1. Install NuGet package

Install the GovUk.Frontend.AspNetCore NuGet package:

Install-Package GovUk.Frontend.AspNetCore

Or via the .NET Core command line interface:

dotnet add package GovUk.Frontend.AspNetCore

2. Configure your ASP.NET Core application

Add services and middleware to your application:

using GovUk.Frontend.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
//...
builder.Services.AddGovUkFrontend();

var app = builder.Build();
app.UseGovUkFrontend();
//...

3. Register tag helpers

In your _ViewImports.cshtml file:

@using GovUk.Frontend.AspNetCore
@addTagHelper GovUk.Frontend.AspNetCore.TagHelpers.*, GovUk.Frontend.AspNetCore

4. Configure your page template

You have several options for configuring your page template.

Using the `_GovUkPageTemplate` Razor view

A Razor view is provided with the standard page template markup and Razor sections where you can add in your header, footer and any custom markup you require.

In your _Layout.cshtml file:

@{
    Layout = "_GovUkPageTemplate";
}

@section BodyStart {
    <govuk-cookie-banner aria-label="Cookie on [name of service]">
        <govuk-cookie-banner-message>
            <govuk-cookie-banner-message-heading>Cookies on [name of service]</govuk-cookie-banner-message-heading>
            <govuk-cookie-banner-message-content>
                <p class="govuk-body">We use some essential cookies to make this service work.</p>
                <p class="govuk-body">We’d also like to use analytics cookies so we can understand how you use the service and make improvements.</p>
            </govuk-cookie-banner-message-content>
            <govuk-cookie-banner-message-actions>
                <govuk-cookie-banner-message-action text="Accept analytics cookies" type="button"/>
                <govuk-cookie-banner-message-action text="Reject analytics cookies" type="button"/>
                <govuk-cookie-banner-message-action-link text="View cookies" href="#"/>
            </govuk-cookie-banner-message-actions>
        </govuk-cookie-banner-message>
    </govuk-cookie-banner>
}

@section Header {
    <govuk-header home-page-url="https://gov.uk/" />

    <govuk-service-navigation service-name="Service name" service-url="#">
        <govuk-service-navigation-nav>
            <govuk-service-navigation-nav-item href="#">Navigation item 1</govuk-service-navigation-nav-item>
            <govuk-service-navigation-nav-item href="#" active="true">Navigation item 2</govuk-service-navigation-nav-item>
            <govuk-service-navigation-nav-item href="#">Navigation item 3</govuk-service-navigation-nav-item>
        </govuk-service-navigation-nav>
    </govuk-service-navigation>
}

@RenderBody()

@section Footer {
    <govuk-footer>
        <govuk-footer-meta>
            <govuk-footer-meta-items>
                <govuk-footer-meta-item href="#">Item 1</govuk-footer-meta-item>
                <govuk-footer-meta-item href="#">Item 2</govuk-footer-meta-item>
                <govuk-footer-meta-item href="#">Item 3</govuk-footer-meta-item>
            </govuk-footer-meta-items>
        </govuk-footer-meta>
    </govuk-footer>
}

The view can be customised by defining the following sections and ViewData/ViewBag variables.

Section name	Description
BeforeContent	Add content that needs to appear outside element. For example: The back link component, breadcrumbs component, phase banner component.
BodyEnd	Add content just before the closing `</body>` element.
BodyStart	Add content after the opening `<body>` element. For example: The cookie banner component.
Footer	Defines the footer content.
Head	Add additional items inside the element. For example: `<meta name="description" content="My page description">`
Header	Defines the header content.
HeadIcons	Override the default icons used for GOV.UK branded pages. For example: `<link rel="shortcut icon" href="favicon.ico" type="image/x-icon" />`
SkipLink	Override the default skip link component.

`ViewData` key	Type	Description
BodyClasses	`string`	Add class(es) to the `<body>` element.
ContainerClasses	`string`	Add class(es) to the container. This is useful if you want to make the page wrapper a fixed width.
HtmlClasses	`string`	Add class(es) to the `<html>` element.
HtmlLang	`string`	Set the language of the whole document. If your `<title>` and `<main>` element are in a different language to the rest of the page, use `HtmlLang` to set the language of the rest of the page.
MainClasses	`string`	Add class(es) to the `<main>` element.
MainLang	`string`	Set the language of the `<main>` element if it's different to `HtmlLang`.
OpengraphImageUrl	`string`	Set the URL for the Open Graph image meta tag. The URL must be absolute, including the protocol and domain name.
Title	`string`	Override the default page title (`<title>` element).
ThemeColor	`string`	Set the toolbar colour on some devices.

Create your own Razor view

If the standard template above is not sufficient, you can create your own Razor view.

Extension methods are provided on IHtmlHelper that simplify the CSS and script imports. GovUkFrontendStyleImports imports CSS stylesheets and should be added to <head>. GovUkFrontendJsEnabledScript declares some inline JavaScript that adds the js-enabled class to the <body> and should be placed at the start of <body>. GovUkFrontendScriptImports imports JavaScript files and should be added to the end of <body>.

The latter two methods take an optional cspNonce parameter; when provided a nonce attribute will be added to the inline scripts.

Example _Layout.cshtml snippet:

@using GovUk.Frontend.AspNetCore

<!DOCTYPE html>
<html>
<head>
    @Html.GovUkFrontendStyleImports()
</head>
<body>
    @Html.GovUkFrontendJsEnabledScript()

    @RenderBody()

    @Html.GovUkFrontendScriptImports()
</body>
</html>

Content security policy (CSP)

There are two built-in mechanisms to help in generating a script-src CSP directive that works correctly with the inline scripts used by the page template.

The preferred option is to use the GetCspScriptHashes extension method on IHtmlHelper. This will return a string that can be inserted directly into the script-src directive in your CSP.

Alternatively, a CSP nonce can be appended to the generated script tags. A delegate must be configured on GovUkFrontendOptions that retrieves a nonce for a given HttpContext.

services.AddGovUkFrontend(options =>
{
    options.GetCspNonceForRequest = context =>
    {
        // Return your nonce here
    };
});

See the Samples.MvcStarter project for an example of this working.

GOV.UK rebrand

The 25 June 2025 rebrand can be enabled by setting Rebrand to true on GovUkOptions:

services.AddGovUkFrontend(options => options.Rebrand = true);

If you're using the _GovUkPageTemplate view, the GOV.UK header and the GOV.UK footer tag helpers you don't need to do anything more.

If not, reference the GOV.UK Frontend release notes to see what needs to be changed.

GOV.UK Frontend assets

By default, static assets (fonts, images, icons etc.) and the compiled JavaScript and CSS from the GOV.UK Frontend package will be hosted automatically.

To disable hosting of these assets or to only serve a subset of the assets, override FrontendPackageHostingOptions:

services.AddGovUkFrontend(options =>
{
    // Host both static assets and compiled assets (the default)
    options.FrontendPackageHostingOptions = FrontendPackageHostingOptions.HostAssets | FrontendPackageHostingOptions.HostCompiledFiles;

    // Don't host anything
    options.FrontendPackageHostingOptions = FrontendPackageHostingOptions.None;

    // Only host static assets
    options.FrontendPackageHostingOptions = FrontendPackageHostingOptions.HostAssets;

    // Only host compiled assets (JavaScript and CSS)
    options.FrontendPackageHostingOptions = FrontendPackageHostingOptions.HostCompiledFiles;
});

If you're using SASS and want to be able to reference the govuk-frontend SASS variables, mixins and functions in your own SASS files, see the SASS sample for an example of how to set up your project.

Components

Validators

Max words validator

Building the library

Install just and make sure it's in your PATH then run:

just install-tools

From there you can run just build to build the library and just test to run the tests.

Name		Name	Last commit message	Last commit date
Latest commit History 836 Commits
.config		.config
.github		.github
docs		docs
samples		samples
src		src
tests		tests
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Directory.Build.props		Directory.Build.props
Directory.Build.targets		Directory.Build.targets
GovUk.Frontend.AspNetCore.sln		GovUk.Frontend.AspNetCore.sln
GovUk.Frontend.AspNetCore.sln.DotSettings		GovUk.Frontend.AspNetCore.sln.DotSettings
LICENSE		LICENSE
README.md		README.md
justfile		justfile
lefthook.yml		lefthook.yml
nuget.config		nuget.config

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Installation

1. Install NuGet package

2. Configure your ASP.NET Core application

3. Register tag helpers

4. Configure your page template

Using the `_GovUkPageTemplate` Razor view

Create your own Razor view

Content security policy (CSP)

GOV.UK rebrand

GOV.UK Frontend assets

Components

Validators

Building the library

About

Uh oh!

Releases 49

Uh oh!

Contributors 6

Languages

License

x-govuk/govuk-frontend-aspnetcore

Folders and files

Latest commit

History

Repository files navigation

Installation

1. Install NuGet package

2. Configure your ASP.NET Core application

3. Register tag helpers

4. Configure your page template

Using the _GovUkPageTemplate Razor view

Create your own Razor view

Content security policy (CSP)

GOV.UK rebrand

GOV.UK Frontend assets

Components

Validators

Building the library

About

Topics

Resources

License

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases 49

Uh oh!

Contributors 6

Languages

Using the `_GovUkPageTemplate` Razor view